HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
copyUtils.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_SDF_COPY_UTILS_H
25 #define PXR_USD_SDF_COPY_UTILS_H
26 
27 /// \file sdf/copyUtils.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/sdf/api.h"
31 
33 #include "pxr/usd/sdf/types.h"
34 
35 #include <hboost/optional.hpp>
36 #include <functional>
37 
39 
40 class SdfPath;
41 class TfToken;
42 class VtValue;
44 
45 /// \name Simple Spec Copying API
46 /// @{
47 
48 /// Utility function for copying spec data at \p srcPath in \p srcLayer to
49 /// \p destPath in \p destLayer.
50 ///
51 /// Copying is performed recursively: all child specs are copied as well.
52 /// Any destination specs that already exist will be overwritten.
53 ///
54 /// Parent specs of the destination are not created, and must exist before
55 /// SdfCopySpec is called, or a coding error will result. For prim parents,
56 /// clients may find it convenient to call SdfCreatePrimInLayer before
57 /// SdfCopySpec.
58 ///
59 /// As a special case, if the top-level object to be copied is a relationship
60 /// target or a connection, the destination spec must already exist. That is
61 /// because we don't want SdfCopySpec to impose any policy on how list edits are
62 /// made; client code should arrange for relationship targets and connections to
63 /// be specified as prepended, appended, deleted, and/or ordered, as needed.
64 ///
65 /// Variant specs may be copied to prim paths and vice versa. When copying a
66 /// variant to a prim, the specifier and typename from the variant's parent
67 /// prim will be used.
68 ///
69 /// Attribute connections, relationship targets, inherit and specializes paths,
70 /// and internal sub-root references that target an object beneath \p srcPath
71 /// will be remapped to target objects beneath \p dstPath.
72 ///
73 SDF_API
74 bool
76  const SdfLayerHandle& srcLayer, const SdfPath& srcPath,
77  const SdfLayerHandle& dstLayer, const SdfPath& dstPath);
78 
79 /// @}
80 
81 /// \name Advanced Spec Copying API
82 /// @{
83 
84 /// Return true if \p field should be copied from the spec at \p srcPath in
85 /// \p srcLayer to the spec at \p dstPath in \p dstLayer. \p fieldInSrc and
86 /// \p fieldInDst indicates whether the field has values at the source and
87 /// destination specs. Return false otherwise.
88 ///
89 /// This function may modify the value that is copied by filling in
90 /// \p valueToCopy with the desired value. \p valueToCopy may also be a
91 /// SdfCopySpecsValueEdit that specifies an editing operation for this field.
92 /// If \p valueToCopy is not set, the field value from the source spec will be
93 /// used as-is. Setting \p valueToCopy to an empty VtValue indicates that the
94 /// field should be removed from the destination spec, if it already exists.
95 ///
96 /// Note that if this function returns true and the source spec has no value
97 /// for \p field (e.g., fieldInSrc == false), the field in the destination
98 /// spec will also be set to no value.
99 using SdfShouldCopyValueFn = std::function<
100  bool(SdfSpecType specType, const TfToken& field,
101  const SdfLayerHandle& srcLayer, const SdfPath& srcPath, bool fieldInSrc,
102  const SdfLayerHandle& dstLayer, const SdfPath& dstPath, bool fieldInDst,
103  hboost::optional<VtValue>* valueToCopy)>;
104 
105 /// \class SdfCopySpecsValueEdit
106 /// Value containing an editing operation for SdfCopySpecs.
107 ///
108 /// The SdfShouldCopyValueFn callback allows users to return a value to copy
109 /// into the destination spec via the \p valueToCopy parameter. However, there
110 /// may be cases where it would be more efficient to perform incremental edits
111 /// using specific SdfLayer API instead.
112 ///
113 /// To accommodate this, consumers may provide a callback that applies a
114 /// scene description edit in \p valueToCopy via an SdfCopySpecsValueEdit
115 /// object.
117 {
118 public:
119  /// Callback to apply a scene description edit to the specified layer and
120  /// spec path.
121  using EditFunction =
122  std::function<void(const SdfLayerHandle&, const SdfPath&)>;
123 
124  explicit SdfCopySpecsValueEdit(const EditFunction& edit) : _edit(edit) { }
125  const EditFunction& GetEditFunction() const { return _edit; }
126 
127  /// SdfCopySpecsValueEdit objects are not comparable, but must provide
128  /// operator== to be stored in a VtValue.
129  bool operator==(const SdfCopySpecsValueEdit& rhs) const { return false; }
130  bool operator!=(const SdfCopySpecsValueEdit& rhs) const { return true; }
131 
132 private:
133  EditFunction _edit;
134 };
135 
136 /// Return true if \p childrenField and the child objects the field represents
137 /// should be copied from the spec at \p srcPath in \p srcLayer to the spec at
138 /// \p dstPath in \p dstLayer. \p fieldInSrc and \p fieldInDst indicates
139 /// whether that field has values at the source and destination specs.
140 /// Return false otherwise.
141 ///
142 /// This function may modify which children are copied by filling in
143 /// \p srcChildren and \p dstChildren with the children to copy and their
144 /// destination. Both of these values must be set, and must contain the same
145 /// number of children.
146 ///
147 /// Note that if this function returns true and the source spec has no value
148 /// for \p childrenField (e.g., fieldInSrc == false), the field in the
149 /// destination spec will also be set to no value, causing any existing children
150 /// to be removed.
151 using SdfShouldCopyChildrenFn = std::function<
152  bool(const TfToken& childrenField,
153  const SdfLayerHandle& srcLayer, const SdfPath& srcPath, bool fieldInSrc,
154  const SdfLayerHandle& dstLayer, const SdfPath& dstPath, bool fieldInDst,
155  hboost::optional<VtValue>* srcChildren,
156  hboost::optional<VtValue>* dstChildren)>;
157 
158 /// SdfShouldCopyValueFn used by the simple version of SdfCopySpec.
159 ///
160 /// Copies all values from the source, transforming path-valued fields prefixed
161 /// with \p srcRootPath to have the prefix \p dstRootPath.
162 ///
163 /// Existing values in the destination will be overwritten by values in the
164 /// source. Any fields in the destination that aren't in the source will be
165 /// cleared.
166 SDF_API
167 bool
169  const SdfPath& srcRootPath, const SdfPath& dstRootPath,
170  SdfSpecType specType, const TfToken& field,
171  const SdfLayerHandle& srcLayer, const SdfPath& srcPath, bool fieldInSrc,
172  const SdfLayerHandle& dstLayer, const SdfPath& dstPath, bool fieldInDst,
173  hboost::optional<VtValue>* valueToCopy);
174 
175 /// SdfShouldCopyChildrenFn used by the simple version of SdfCopySpec.
176 ///
177 /// Copies all child values from the source, transforming path-valued fields
178 /// prefixed with \p srcRootPath to have the prefix \p dstRootPath.
179 ///
180 /// Existing values in the destination will be overwritten by values in the
181 /// source. Any fields in the destination that aren't in the source will be
182 /// cleared.
183 SDF_API
184 bool
186  const SdfPath& srcRootPath, const SdfPath& dstRootPath,
187  const TfToken& childrenField,
188  const SdfLayerHandle& srcLayer, const SdfPath& srcPath, bool fieldInSrc,
189  const SdfLayerHandle& dstLayer, const SdfPath& dstPath, bool fieldInDst,
190  hboost::optional<VtValue>* srcChildren,
191  hboost::optional<VtValue>* dstChildren);
192 
193 /// Utility function for copying spec data at \p srcPath in \p srcLayer to
194 /// \p destPath in \p destLayer. Various behaviors (such as which parts of the
195 /// spec to copy) are controlled by the supplied \p shouldCopyValueFn and
196 /// \p shouldCopyChildrenFn.
197 ///
198 /// Copying is performed recursively: all child specs are copied as well, except
199 /// where prevented by \p shouldCopyChildrenFn.
200 ///
201 /// Parent specs of the destination are not created, and must exist before
202 /// SdfCopySpec is called, or a coding error will result. For prim parents,
203 /// clients may find it convenient to call SdfCreatePrimInLayer before
204 /// SdfCopySpec.
205 ///
206 /// Variant specs may be copied to prim paths and vice versa. When copying a
207 /// variant to a prim, the specifier and typename from the variant's parent
208 /// prim will be used.
209 ///
210 /// As a special case, if the top-level object to be copied is a relationship
211 /// target or a connection, the destination spec must already exist. That is
212 /// because we don't want SdfCopySpec to impose any policy on how list edits are
213 /// made; client code should arrange for relationship targets and connections to
214 /// be specified as prepended, appended, deleted, and/or ordered, as needed.
215 ///
216 SDF_API
217 bool
219  const SdfLayerHandle& srcLayer, const SdfPath& srcPath,
220  const SdfLayerHandle& dstLayer, const SdfPath& dstPath,
221  const SdfShouldCopyValueFn& shouldCopyValueFn,
222  const SdfShouldCopyChildrenFn& shouldCopyChildrenFn);
223 
224 /// @}
225 
227 
228 #endif // PXR_USD_SDF_COPY_UTILS_H
Definition: layer.h:94
SDF_API bool SdfShouldCopyChildren(const SdfPath &srcRootPath, const SdfPath &dstRootPath, const TfToken &childrenField, const SdfLayerHandle &srcLayer, const SdfPath &srcPath, bool fieldInSrc, const SdfLayerHandle &dstLayer, const SdfPath &dstPath, bool fieldInDst, hboost::optional< VtValue > *srcChildren, hboost::optional< VtValue > *dstChildren)
std::function< void(const SdfLayerHandle &, const SdfPath &)> EditFunction
Definition: copyUtils.h:122
Definition: token.h:87
bool operator==(const SdfCopySpecsValueEdit &rhs) const
Definition: copyUtils.h:129
bool operator!=(const SdfCopySpecsValueEdit &rhs) const
Definition: copyUtils.h:130
Definition: path.h:291
const EditFunction & GetEditFunction() const
Definition: copyUtils.h:125
SdfCopySpecsValueEdit(const EditFunction &edit)
Definition: copyUtils.h:124
#define SDF_API
Definition: api.h:40
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1441
std::function< bool(const TfToken &childrenField, const SdfLayerHandle &srcLayer, const SdfPath &srcPath, bool fieldInSrc, const SdfLayerHandle &dstLayer, const SdfPath &dstPath, bool fieldInDst, hboost::optional< VtValue > *srcChildren, hboost::optional< VtValue > *dstChildren)> SdfShouldCopyChildrenFn
Definition: copyUtils.h:156
SdfSpecType
Definition: types.h:90
SDF_API bool SdfCopySpec(const SdfLayerHandle &srcLayer, const SdfPath &srcPath, const SdfLayerHandle &dstLayer, const SdfPath &dstPath)
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
std::function< bool(SdfSpecType specType, const TfToken &field, const SdfLayerHandle &srcLayer, const SdfPath &srcPath, bool fieldInSrc, const SdfLayerHandle &dstLayer, const SdfPath &dstPath, bool fieldInDst, hboost::optional< VtValue > *valueToCopy)> SdfShouldCopyValueFn
Definition: copyUtils.h:103
SDF_DECLARE_HANDLES(SdfLayer)
SDF_API bool SdfShouldCopyValue(const SdfPath &srcRootPath, const SdfPath &dstRootPath, SdfSpecType specType, const TfToken &field, const SdfLayerHandle &srcLayer, const SdfPath &srcPath, bool fieldInSrc, const SdfLayerHandle &dstLayer, const SdfPath &dstPath, bool fieldInDst, hboost::optional< VtValue > *valueToCopy)
Definition: value.h:167