HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
changes.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_PCP_CHANGES_H
25 #define PXR_USD_PCP_CHANGES_H
26 
27 /// \file pcp/changes.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/pcp/api.h"
31 #include "pxr/usd/sdf/changeList.h"
33 #include "pxr/usd/sdf/path.h"
34 #include "pxr/usd/sdf/types.h"
36 #include "pxr/base/tf/span.h"
37 
38 #include <map>
39 #include <set>
40 
42 
45 
46 class PcpCache;
47 class PcpSite;
48 
49 /// \class PcpLayerStackChanges
50 ///
51 /// Types of changes per layer stack.
52 ///
54 public:
55  /// Must rebuild the layer tree. Implies didChangeLayerOffsets.
57 
58  /// Must rebuild the layer offsets.
60 
61  /// Must rebuild the relocation tables.
63 
64  /// A significant layer stack change means the composed opinions of
65  /// the layer stack may have changed in arbitrary ways. This
66  /// represents a coarse invalidation. By way of contrast, an example
67  /// of an insignificant change is adding or removing a layer empty
68  /// of opinions.
70 
71  /// New relocation maps for this layer stack.
72  /// If didChangeRelocates is true, these fields will be populated
73  /// as part of determining the changes to this layer stack.
74  /// However, we do not immediately apply those changes to the
75  /// layer stack; we store them here and commit them in Apply().
81 
82  /// Paths that are affected by the above relocation changes.
84 
86  didChangeLayers(false),
87  didChangeLayerOffsets(false),
88  didChangeRelocates(false),
90  {}
91 };
92 
93 /// \class PcpCacheChanges
94 ///
95 /// Types of changes per cache.
96 ///
98 public:
99  enum TargetType {
102  };
103 
104  /// Must rebuild the indexes at and below each path. This
105  /// implies rebuilding the prim/property stacks at
106  /// and below each path.
108 
109  /// Must rebuild the prim/property stacks at each path.
111 
112  /// Must rebuild the prim indexes at each path. This implies rebuilding
113  /// the prim stack at each path.
115 
116  /// Must rebuild the connections/targets at each path.
117  std::map<SdfPath, int, SdfPath::FastLessThan> didChangeTargets;
118 
119  typedef std::map<SdfPath, SdfPath> PathEditMap;
120 
121  /// Must update the path on every namespace object at and below each
122  /// given path. The first path is the old path to the object and the
123  /// second path is the new path.
125 
126 private:
127  friend class PcpCache;
128  friend class PcpChanges;
129 
130  // Must rebuild the prim/property stacks at each path due to a change
131  // that only affects the internal representation of the stack and
132  // not its contents. Because this causes no externally-observable
133  // changes in state, clients do not need to be aware of these changes.
134  SdfPathSet _didChangeSpecsInternal;
135 };
136 
137 /// Structure used to temporarily retain layers and layerStacks within
138 /// a code block. Analogous to the autorelease pool in obj-c.
139 class PcpLifeboat {
140 public:
141  PcpLifeboat();
142  ~PcpLifeboat();
143 
144  /// Ensure that \p layer exists until this object is destroyed.
145  void Retain(const SdfLayerRefPtr& layer);
146 
147  /// Ensure that \p layerStack exists until this object is destroyed.
148  void Retain(const PcpLayerStackRefPtr& layerStack);
149 
150  /// Returns reference to the set of layer stacks currently being held
151  /// in the lifeboat.
152  const std::set<PcpLayerStackRefPtr>& GetLayerStacks() const;
153 
154  /// Swap the contents of this and \p other.
155  void Swap(PcpLifeboat& other);
156 
157 private:
158  std::set<SdfLayerRefPtr> _layers;
159  std::set<PcpLayerStackRefPtr> _layerStacks;
160 };
161 
162 /// \class PcpChanges
163 ///
164 /// Describes Pcp changes.
165 ///
166 /// Collects changes to Pcp necessary to reflect changes in Sd. It does
167 /// not cause any changes to any Pcp caches, layer stacks, etc; it only
168 /// computes what changes would be necessary to Pcp to reflect the Sd
169 /// changes.
170 ///
171 class PcpChanges {
172 public:
175 
176  /// Breaks down \p changes into individual changes on the caches in
177  /// \p caches. This simply translates data in \p changes into other
178  /// Did...() calls on this object.
179  ///
180  /// Clients will typically call this method once then call \c Apply() or
181  /// get the changes using \c GetLayerStackChanges() and
182  /// \c GetCacheChanges().
183  PCP_API
184  void DidChange(const TfSpan<const PcpCache*> &caches,
185  const SdfLayerChangeListVec& changes);
186 
187  /// Tries to load the sublayer of \p layer at \p sublayerPath. If
188  /// successful, any layer stack using \p layer is marked as having changed
189  /// and all prims in \p cache using any prim in any of those layer stacks
190  /// are marked as changed.
191  PCP_API
192  void DidMaybeFixSublayer(const PcpCache* cache,
193  const SdfLayerHandle& layer,
194  const std::string& assetPath);
195 
196  /// Tries to load the asset at \p assetPath. If successful, any prim
197  /// in \p cache using the site \p site is marked as changed.
198  PCP_API
199  void DidMaybeFixAsset(const PcpCache* cache,
200  const PcpSite& site,
201  const SdfLayerHandle& srcLayer,
202  const std::string& assetPath);
203 
204  /// The layer identified by \p layerId was muted in \p cache.
205  PCP_API
206  void DidMuteLayer(const PcpCache* cache, const std::string& layerId);
207 
208  /// The layer identified by \p layerId was unmuted in \p cache.
209  PCP_API
210  void DidUnmuteLayer(const PcpCache* cache, const std::string& layerId);
211 
212  /// The sublayer tree changed. This often, but doesn't always, imply that
213  /// anything and everything may have changed. If clients want to indicate
214  /// that anything and everything may have changed they should call this
215  /// method and \c DidChangePrimGraph() with the absolute root path.
216  PCP_API
217  void DidChangeLayers(const PcpCache* cache);
218 
219  /// The sublayer offsets changed.
220  PCP_API
221  void DidChangeLayerOffsets(const PcpCache* cache);
222 
223  /// The object at \p path changed significantly enough to require
224  /// recomputing the entire prim or property index. A significant change
225  /// implies changes to every namespace descendant's index, specs, and
226  /// dependencies.
227  PCP_API
228  void DidChangeSignificantly(const PcpCache* cache, const SdfPath& path);
229 
230  /// The spec stack for the prim or property has changed, due to the
231  /// addition or removal of the spec in \p changedLayer at \p changedPath.
232  /// This is used when inert prims/properties are added or removed or when
233  /// any change requires rebuilding the property stack. It implies that
234  /// dependencies on those specs has changed.
235  PCP_API
236  void DidChangeSpecs(const PcpCache* cache, const SdfPath& path,
237  const SdfLayerHandle& changedLayer,
238  const SdfPath& changedPath);
239 
240  /// The spec stack for the prim or property at \p path in \p cache has
241  /// changed.
242  PCP_API
243  void DidChangeSpecStack(const PcpCache* cache, const SdfPath& path);
244 
245  /// The connections on the attribute or targets on the relationship have
246  /// changed.
247  PCP_API
248  void DidChangeTargets(const PcpCache* cache, const SdfPath& path,
249  PcpCacheChanges::TargetType targetType);
250 
251  /// The relocates that affect prims and properties at and below
252  /// the given cache path have changed.
253  PCP_API
254  void DidChangeRelocates(const PcpCache* cache, const SdfPath& path);
255 
256  /// The composed object at \p oldPath was moved to \p newPath. This
257  /// implies every corresponding Sd change. This object will subsume
258  /// those Sd changes under this higher-level move. Sd path changes
259  /// that are not so subsumed will be converted to DidChangePrimGraph()
260  /// and/or DidChangeSpecs() changes.
261  PCP_API
262  void DidChangePaths(const PcpCache* cache,
263  const SdfPath& oldPath, const SdfPath& newPath);
264 
265  /// Remove any changes for \p cache.
266  PCP_API
267  void DidDestroyCache(const PcpCache* cache);
268 
269  /// Swap the contents of this and \p other.
270  PCP_API
271  void Swap(PcpChanges& other);
272 
273  /// Returns \c true iff there are no changes.
274  PCP_API
275  bool IsEmpty() const;
276 
277  typedef std::map<PcpLayerStackPtr, PcpLayerStackChanges> LayerStackChanges;
278  typedef std::map<PcpCache*, PcpCacheChanges> CacheChanges;
279 
280  /// Returns a map of all of the layer stack changes. Note that some
281  /// keys may be to expired layer stacks.
282  PCP_API
284 
285  /// Returns a map of all of the cache changes.
286  PCP_API
287  const CacheChanges& GetCacheChanges() const;
288 
289  /// Returns the lifeboat responsible for maintaining the lifetime of
290  /// layers and layer stacks during change processing. Consumers may
291  /// inspect this object to determine which of these objects, if any,
292  /// had their lifetimes affected during change processing.
293  PCP_API
294  const PcpLifeboat& GetLifeboat() const;
295 
296  /// Applies the changes to the layer stacks and caches.
297  PCP_API
298  void Apply() const;
299 
300 private:
301  // Internal data type for namespace edits from Sd.
302  typedef std::map<PcpCache*, PcpCacheChanges::PathEditMap> _RenameChanges;
303 
304  // Returns the PcpLayerStackChanges for the given cache's layer stack.
305  PcpLayerStackChanges& _GetLayerStackChanges(const PcpCache* cache);
306 
307  // Returns the PcpLayerStackChanges for the given layer stack.
308  PcpLayerStackChanges& _GetLayerStackChanges(const PcpLayerStackPtr&);
309 
310  // Returns the PcpCacheChanges for the given cache.
311  PcpCacheChanges& _GetCacheChanges(const PcpCache* cache);
312 
313  // Returns the PcpCacheChanges::PathEditMap for the given cache.
314  PcpCacheChanges::PathEditMap& _GetRenameChanges(const PcpCache* cache);
315 
316 
317  // Optimize the changes.
318  void _Optimize() const;
319 
320  // Optimize the changes.
321  void _Optimize();
322 
323  // Optimize the changes for a given cache.
324  void _Optimize(PcpCacheChanges*);
325 
326  // Optimize path changes.
327  void _OptimizePathChanges(const PcpCache* cache, PcpCacheChanges* changes,
328  PcpCacheChanges::PathEditMap* pathChanges);
329 
330  // Sublayer change type for _DidChangeSublayer.
331  enum _SublayerChangeType {
332  _SublayerAdded,
333  _SublayerRemoved
334  };
335 
336  // Helper function for loading a sublayer of \p layer at \p sublayerPath
337  // for processing changes described by \p sublayerChange.
338  SdfLayerRefPtr _LoadSublayerForChange(const PcpCache* cache,
339  const SdfLayerHandle& layer,
340  const std::string& sublayerPath,
341  _SublayerChangeType changeType) const;
342 
343  // Helper function for loading a sublayer at \p sublayerPath
344  // for processing changes described by \p sublayerChange.
345  SdfLayerRefPtr _LoadSublayerForChange(const PcpCache* cache,
346  const std::string& sublayerPath,
347  _SublayerChangeType changeType) const;
348 
349  // Propagates changes to \p sublayer specified by \p sublayerChange to
350  // the dependents of that sublayer. This includes all layer stacks
351  // that include the sublayer.
352  void _DidChangeSublayerAndLayerStacks(const PcpCache* cache,
353  const PcpLayerStackPtrVector& stacks,
354  const std::string& sublayerPath,
355  const SdfLayerHandle& sublayer,
356  _SublayerChangeType sublayerChange,
357  std::string* debugSummary);
358 
359  // Propagates changes to \p sublayer specified by \p sublayerChange to
360  // the dependents of that sublayer.
361  void _DidChangeSublayer(const PcpCache* cache,
362  const PcpLayerStackPtrVector& layerStacks,
363  const std::string& sublayerPath,
364  const SdfLayerHandle& sublayer,
365  _SublayerChangeType sublayerChange,
366  std::string* debugSummary,
367  bool *significant);
368 
369  // Mark the layer stack as having changed.
370  void _DidChangeLayerStack(const PcpLayerStackPtr& layerStack,
371  bool requiresLayerStackChange,
372  bool requiresLayerStackOffsetsChange,
373  bool requiresSignificantChange);
374 
375  // Mark the layer stack's relocations as having changed.
376  // Recompute the new relocations, storing the result in the Changes,
377  // so that change-processing can determine which other caches it
378  // needs to invalidate.
379  void _DidChangeLayerStackRelocations(
380  const TfSpan<const PcpCache*>& caches,
381  const PcpLayerStackPtr & layerStack,
382  std::string* debugSummary);
383 
384  // Register changes to any prim indexes in \p caches that are affected
385  // by a change to a layer's resolved path used by \p layerStack.
386  void _DidChangeLayerStackResolvedPath(
387  const TfSpan<const PcpCache*>& caches,
388  const PcpLayerStackPtr& layerStack,
389  std::string* debugSummary);
390 
391  // The spec stack for the prim or property index at \p path must be
392  // recomputed due to a change that affects only the internal representation
393  // of the stack and not its contents.
394  void _DidChangeSpecStackInternal(
395  const PcpCache* cache, const SdfPath& path);
396 
397 private:
398  LayerStackChanges _layerStackChanges;
399  CacheChanges _cacheChanges;
400  _RenameChanges _renameChanges;
401  mutable PcpLifeboat _lifeboat;
402 };
403 
405 
406 #endif // PXR_USD_PCP_CHANGES_H
PCP_API void DidChange(const TfSpan< const PcpCache * > &caches, const SdfLayerChangeListVec &changes)
Definition: layer.h:93
PXR_NAMESPACE_OPEN_SCOPE SDF_DECLARE_HANDLES(SdfLayer)
std::map< SdfPath, SdfPath > PathEditMap
Definition: changes.h:119
PCP_API void DidMaybeFixSublayer(const PcpCache *cache, const SdfLayerHandle &layer, const std::string &assetPath)
SdfRelocatesMap newIncrementalRelocatesTargetToSource
Definition: changes.h:79
SdfPathSet didChangePrims
Definition: changes.h:114
PCP_API void DidChangeLayers(const PcpCache *cache)
std::map< SdfPath, SdfPath > SdfRelocatesMap
A map of source SdfPaths to target SdfPaths for relocation.
Definition: types.h:273
TF_DECLARE_WEAK_AND_REF_PTRS(PcpLayerStack)
PCP_API ~PcpChanges()
Definition: cache.h:91
PCP_API void Apply() const
Applies the changes to the layer stacks and caches.
Definition: site.h:46
PCP_API const CacheChanges & GetCacheChanges() const
Returns a map of all of the cache changes.
SdfPathVector newRelocatesPrimPaths
Definition: changes.h:80
PCP_API const LayerStackChanges & GetLayerStackChanges() const
PCP_API void DidChangeRelocates(const PcpCache *cache, const SdfPath &path)
PCP_API void DidChangeSignificantly(const PcpCache *cache, const SdfPath &path)
SdfPathSet pathsAffectedByRelocationChanges
Paths that are affected by the above relocation changes.
Definition: changes.h:83
Definition: span.h:87
PathEditMap didChangePath
Definition: changes.h:124
PCP_API const PcpLifeboat & GetLifeboat() const
std::map< SdfPath, int, SdfPath::FastLessThan > didChangeTargets
Must rebuild the connections/targets at each path.
Definition: changes.h:117
PCP_API void DidChangeSpecs(const PcpCache *cache, const SdfPath &path, const SdfLayerHandle &changedLayer, const SdfPath &changedPath)
PCP_API PcpChanges()
PCP_API void DidDestroyCache(const PcpCache *cache)
Remove any changes for cache.
PCP_API void DidMuteLayer(const PcpCache *cache, const std::string &layerId)
The layer identified by layerId was muted in cache.
void Swap(PcpLifeboat &other)
Swap the contents of this and other.
SdfRelocatesMap newIncrementalRelocatesSourceToTarget
Definition: changes.h:78
bool didChangeLayers
Must rebuild the layer tree. Implies didChangeLayerOffsets.
Definition: changes.h:56
std::map< PcpLayerStackPtr, PcpLayerStackChanges > LayerStackChanges
Definition: changes.h:277
Definition: path.h:288
PCP_API void Swap(PcpChanges &other)
Swap the contents of this and other.
std::vector< class SdfPath > SdfPathVector
A vector of SdfPaths.
Definition: path.h:209
PCP_API void DidChangePaths(const PcpCache *cache, const SdfPath &oldPath, const SdfPath &newPath)
std::set< class SdfPath > SdfPathSet
A set of SdfPaths.
Definition: path.h:207
std::map< PcpCache *, PcpCacheChanges > CacheChanges
Definition: changes.h:278
GLsizei const GLchar *const * path
Definition: glew.h:6461
SdfPathSet didChangeSpecs
Must rebuild the prim/property stacks at each path.
Definition: changes.h:110
bool didChangeRelocates
Must rebuild the relocation tables.
Definition: changes.h:62
GLsizei const GLchar *const * string
Definition: glew.h:1844
PCP_API void DidChangeLayerOffsets(const PcpCache *cache)
The sublayer offsets changed.
std::vector< std::pair< SdfLayerHandle, SdfChangeList > > SdfLayerChangeListVec
Definition: changeList.h:42
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
SdfPathSet didChangeSignificantly
Definition: changes.h:107
PCP_API bool IsEmpty() const
Returns true iff there are no changes.
SdfRelocatesMap newRelocatesTargetToSource
Definition: changes.h:76
PCP_API void DidChangeTargets(const PcpCache *cache, const SdfPath &path, PcpCacheChanges::TargetType targetType)
GLint GLboolean GLint layer
Definition: glew.h:3601
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
bool didChangeSignificantly
Definition: changes.h:69
PCP_API void DidMaybeFixAsset(const PcpCache *cache, const PcpSite &site, const SdfLayerHandle &srcLayer, const std::string &assetPath)
SdfRelocatesMap newRelocatesSourceToTarget
Definition: changes.h:77
const std::set< PcpLayerStackRefPtr > & GetLayerStacks() const
PCP_API void DidUnmuteLayer(const PcpCache *cache, const std::string &layerId)
The layer identified by layerId was unmuted in cache.
void Retain(const SdfLayerRefPtr &layer)
Ensure that layer exists until this object is destroyed.
PCP_API void DidChangeSpecStack(const PcpCache *cache, const SdfPath &path)
bool didChangeLayerOffsets
Must rebuild the layer offsets.
Definition: changes.h:59
#define PCP_API
Definition: api.h:40