HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
stitch.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_STITCH_H
25 #define PXR_USD_USD_UTILS_STITCH_H
26 
27 /// \file usdUtils/stitch.h
28 ///
29 /// Collection of module-scoped utilities for combining layers.
30 /// These utilize the convention of a strong and a weak layer. The strong
31 /// layer will be the first parameter to the function and will always have
32 /// precedence in conflicts during the merge.
33 
34 #include "pxr/pxr.h"
35 #include "pxr/usd/usdUtils/api.h"
37 #include "pxr/usd/sdf/spec.h"
38 
39 #include <functional>
40 
42 
44 
45 /// Merge all scene description in \p weakLayer into \p strongLayer.
46 ///
47 /// Prims and properties in \p weakLayer that do not exist in \p strongLayer
48 /// will be copied into \p strongLayer. Prims and properties that do
49 /// exist in \p strongLayer will be merged with the existing scene
50 /// description.
51 ///
52 /// Merging prims and properties is done on a field-by-field basis.
53 /// In general, if a field has a value in \p strongLayer, the value from
54 /// \p weakLayer will be ignored. However, certain fields have special
55 /// rules for merging values together:
56 ///
57 /// - For map and dictionary-valued fields (including time samples),
58 /// a dictionary merge is performed; values in the weaker dictionary
59 /// are copied into the stronger dictionary only if the key does not
60 /// already exist.
61 ///
62 /// - For listOp-valued fields, the listOps will be combined into a
63 /// single listOp. The historical "add" and "reorder" list op operations
64 /// cannot be combined in this way; "add" will be converted to "append",
65 /// and "reorder" will be discarded.
66 ///
67 /// - The minimum startTimeCode value and maximum endTimeCode value will
68 /// be used.
71  const SdfLayerHandle& strongLayer,
72  const SdfLayerHandle& weakLayer);
73 
74 /// Merge the scene description for \p weakObj into \p strongObj.
75 ///
76 /// See documentation on UsdUtilsStitchLayers for a description of
77 /// the merging behavior.
80  const SdfSpecHandle& strongObj,
81  const SdfSpecHandle& weakObj);
82 
83 /// \name Advanced Stitching API
84 /// @{
85 
86 /// Status enum returned by UsdUtilsStitchValueFn describing the
87 /// desired value stitching behavior.
89 {
90  NoStitchedValue, ///< Don't stitch values for this field.
91  UseDefaultValue, ///< Use the default stitching behavior for this field.
92  UseSuppliedValue ///< Use the value supplied in stitchedValue.
93 };
94 
95 /// Callback for customizing how values are stitched together.
96 ///
97 /// This callback will be invoked for each field being stitched from the
98 /// source spec at \p path in \p weakLayer to the destination spec at
99 /// \p path in \p strongLayer. \p fieldInStrongLayer and \p fieldInWeakLayer
100 /// indicates whether the field has values in either layer.
101 ///
102 /// The callback should return a UsdUtilsStitchValueStatus to indicate the
103 /// desired behavior. Note that if the callback returns UseSuppliedValue and
104 /// supplies an empty VtValue in \p stitchedValue, the field will be removed
105 /// from the destination spec.
106 using UsdUtilsStitchValueFn = std::function<
108  const TfToken& field, const SdfPath& path,
109  const SdfLayerHandle& strongLayer, bool fieldInStrongLayer,
110  const SdfLayerHandle& weakLayer, bool fieldInWeakLayer,
111  VtValue* stitchedValue)>;
112 
113 /// Advanced version of UsdUtilsStitchLayers that accepts a \p stitchValueFn
114 /// callback to customize how fields in \p strongLayer and \p weakLayer are
115 /// stitched together. See documentation on UsdUtilsStitchValueFn for more
116 /// details.
119  const SdfLayerHandle& strongLayer,
120  const SdfLayerHandle& weakLayer,
121  const UsdUtilsStitchValueFn& stitchValueFn);
122 
123 /// Advanced version of UsdUtilsStitchInfo that accepts a \p stitchValueFn
124 /// callback to customize how fields in \p strongObj and \p weakObj are
125 /// stitched together. See documentation on UsdUtilsStitchValueFn for more
126 /// details.
128 void UsdUtilsStitchInfo(
129  const SdfSpecHandle& strongObj,
130  const SdfSpecHandle& weakObj,
131  const UsdUtilsStitchValueFn& stitchValueFn);
132 
133 /// @}
134 
136 
137 #endif /* PXR_USD_USD_UTILS_STITCH_H */
Definition: layer.h:94
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
Definition: token.h:87
Definition: path.h:291
Use the default stitching behavior for this field.
std::function< UsdUtilsStitchValueStatus(const TfToken &field, const SdfPath &path, const SdfLayerHandle &strongLayer, bool fieldInStrongLayer, const SdfLayerHandle &weakLayer, bool fieldInWeakLayer, VtValue *stitchedValue)> UsdUtilsStitchValueFn
Definition: stitch.h:111
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1441
Use the value supplied in stitchedValue.
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USDUTILS_API void UsdUtilsStitchLayers(const SdfLayerHandle &strongLayer, const SdfLayerHandle &weakLayer)
PXR_NAMESPACE_OPEN_SCOPE SDF_DECLARE_HANDLES(SdfLayer)
Don't stitch values for this field.
#define USDUTILS_API
Definition: api.h:40
USDUTILS_API void UsdUtilsStitchInfo(const SdfSpecHandle &strongObj, const SdfSpecHandle &weakObj)
Definition: value.h:167
UsdUtilsStitchValueStatus
Definition: stitch.h:88