HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
cache.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the terms set forth in the LICENSE.txt file available at
5 // https://openusd.org/license.
6 //
7 #ifndef PXR_USD_PCP_CACHE_H
8 #define PXR_USD_PCP_CACHE_H
9 
10 #include "pxr/pxr.h"
11 #include "pxr/usd/pcp/api.h"
12 #include "pxr/usd/pcp/dependency.h"
13 #include "pxr/usd/pcp/errors.h"
15 #include "pxr/usd/pcp/primIndex.h"
18 #include "pxr/usd/sdf/path.h"
19 #include "pxr/usd/sdf/pathTable.h"
20 
21 #include "pxr/usd/ar/ar.h"
25 #include "pxr/base/tf/hashset.h"
26 
27 #include <memory>
28 #include <string>
29 #include <unordered_set>
30 #include <vector>
31 
33 
34 // Forward declarations:
35 class PcpChanges;
36 class PcpCacheChanges;
37 class Pcp_Dependencies;
39 class PcpLifeboat;
40 class PcpNodeRef;
41 class PcpMapFunction;
42 
44 TF_DECLARE_WEAK_AND_REF_PTRS(Pcp_LayerStackRegistry);
46 
47 /// \class PcpCache
48 ///
49 /// PcpCache is the context required to make requests of the Pcp
50 /// composition algorithm and cache the results.
51 ///
52 /// Because the algorithms are recursive -- making a request typically
53 /// makes other internal requests to solve subproblems -- caching
54 /// subproblem results is required for reasonable performance, and
55 /// so this cache is the only entrypoint to the algorithms.
56 ///
57 /// There is a set of parameters that affect the composition results:
58 ///
59 /// \li variant fallbacks: per named variant set, an ordered list of
60 /// fallback values to use when composing a prim that defines
61 /// a variant set but does not specify a selection
62 /// \li payload inclusion set: an SdfPath set used to identify which
63 /// prims should have their payloads included during composition;
64 /// this is the basis for explicit control over the "working set"
65 /// of composition
66 /// \li file format target: the file format target that Pcp will request
67 /// when opening scene description layers
68 /// \li "USD mode" configures the Pcp composition algorithm to provide
69 /// only a custom, lighter subset of the full feature set, as needed
70 /// by the Universal Scene Description system
71 ///
72 /// There are a number of different computations that can be requested.
73 /// These include computing a layer stack from a PcpLayerStackIdentifier,
74 /// computing a prim index or prim stack, and computing a property index.
75 ///
76 class PcpCache
77 {
78  PcpCache(PcpCache const &) = delete;
79  PcpCache &operator=(PcpCache const &) = delete;
80 public:
81  /// Construct a PcpCache to compose results for the layer stack identified
82  /// by \a layerStackIdentifier.
83  ///
84  /// If \p fileFormatTarget is given, Pcp will specify \p fileFormatTarget
85  /// as the file format target when searching for or opening a layer.
86  ///
87  /// If \p usd is true, computation of prim indices and composition of prim
88  /// child names are performed without relocates, inherits, permissions,
89  /// symmetry, or payloads, and without populating the prim stack and
90  /// gathering its dependencies.
91  PCP_API
92  PcpCache(const PcpLayerStackIdentifier & layerStackIdentifier,
93  const std::string& fileFormatTarget = std::string(),
94  bool usd = false);
96 
97  /// \name Parameters
98  /// @{
99 
100  /// Get the identifier of the layerStack used for composition.
101  PCP_API
103 
104  /// Get the layer stack for GetLayerStackIdentifier(). Note that
105  /// this will neither compute the layer stack nor report errors.
106  /// So if the layer stack has not been computed yet this will
107  /// return \c NULL. Use ComputeLayerStack() if you need to
108  /// compute the layer stack if it hasn't been computed already
109  /// and/or get errors caused by computing the layer stack.
110  PCP_API
111  PcpLayerStackPtr GetLayerStack() const;
112 
113  /// Return true if this cache's root layer stack is \p layerStack, false
114  /// otherwise. This is functionally equivalent to comparing against the
115  /// result of GetLayerStack(), but does not require constructing a TfWeakPtr
116  /// or any refcount operations.
117  bool HasRootLayerStack(PcpLayerStackRefPtr const &layerStack) const {
118  return layerStack == _layerStack;
119  }
120 
121  /// \overload
122  PCP_API
123  bool HasRootLayerStack(PcpLayerStackPtr const &layerStack) const;
124 
125  /// Return true if the cache is configured in Usd mode.
126  PCP_API
127  bool IsUsd() const;
128 
129  /// Returns the file format target this cache is configured for.
130  PCP_API
131  const std::string& GetFileFormatTarget() const;
132 
133  /// Get the list of fallbacks to attempt to use when evaluating
134  /// variant sets that lack an authored selection.
135  PCP_API
137 
138  /// Set the list of fallbacks to attempt to use when evaluating
139  /// variant sets that lack an authored selection.
140  ///
141  /// If \p changes is not \c NULL then it's adjusted to reflect the
142  /// changes necessary to see the change in standin preferences,
143  /// otherwise those changes are applied immediately.
144  PCP_API
145  void SetVariantFallbacks( const PcpVariantFallbackMap & map,
146  PcpChanges* changes = NULL );
147 
148  /// Return true if the payload is included for the given path.
149  PCP_API
150  bool IsPayloadIncluded(const SdfPath &path) const;
151 
152  /// Returns the payloads requested for inclusion.
153  using PayloadSet = std::unordered_set<SdfPath, SdfPath::Hash>;
154  PCP_API
155  PayloadSet const &GetIncludedPayloads() const;
156 
157  /// Request payloads to be included or excluded from composition.
158  /// \param pathsToInclude is a set of paths to add to the set for
159  /// payload inclusion.
160  /// \param pathsToExclude is a set of paths to remove from the set for
161  /// payload inclusion.
162  /// \param changes if not \c NULL, is adjusted to reflect the changes
163  /// necessary to see the change in payloads; otherwise those
164  /// changes are applied immediately.
165  /// \note If a path is listed in both pathsToInclude and pathsToExclude,
166  /// it will be treated as an inclusion only.
167  ///
168  PCP_API
169  void RequestPayloads( const SdfPathSet & pathsToInclude,
170  const SdfPathSet & pathsToExclude,
171  PcpChanges* changes = NULL );
172 
173  /// Request layers to be muted or unmuted in this cache. Muted layers
174  /// are ignored during composition and do not appear in any layer
175  /// stacks. The root layer of this stage may not be muted; attempting
176  /// to do so will generate a coding error. If the root layer of a
177  /// reference or payload layer stack is muted, the behavior is as if
178  /// the muted layer did not exist, which means a composition error will
179  /// be generated.
180  ///
181  /// A canonical identifier for each layer in \p layersToMute will be
182  /// computed using ArResolver::CreateIdentifier using the cache's root
183  /// layer as the anchoring asset. If an identifier contains a file
184  /// format target that matches this cache's file format target, that
185  /// argument will be removed from the identifier. Any layer encountered
186  /// during composition with the same canonical identifier will be
187  /// considered muted and ignored.
188  ///
189  /// Note that muting a layer will cause this cache to release all
190  /// references to that layer. If no other client is holding on to
191  /// references to that layer, it will be unloaded. In this case, if
192  /// there are unsaved edits to the muted layer, those edits are lost.
193  /// Since anonymous layers are not serialized, muting an anonymous
194  /// layer will cause that layer and its contents to be lost in this
195  /// case.
196  ///
197  /// If \p changes is not \c nullptr, it is adjusted to reflect the
198  /// changes necessary to see the change in muted layers. Otherwise,
199  /// those changes are applied immediately.
200  ///
201  /// \p newLayersMuted and \p newLayersUnmuted contains the pruned vector
202  /// of layers which are muted or unmuted by this call to RequestLayerMuting.
203  ///
204  PCP_API
205  void RequestLayerMuting(const std::vector<std::string>& layersToMute,
206  const std::vector<std::string>& layersToUnmute,
207  PcpChanges* changes = nullptr,
208  std::vector<std::string>* newLayersMuted = nullptr,
209  std::vector<std::string>* newLayersUnmuted =
210  nullptr);
211 
212  /// Returns the list of canonical identifiers for muted layers
213  /// in this cache. See documentation on RequestLayerMuting for
214  /// more details.
215  PCP_API
216  const std::vector<std::string>& GetMutedLayers() const;
217 
218  /// Returns true if the layer specified by \p layerIdentifier is
219  /// muted in this cache, false otherwise. If \p layerIdentifier
220  /// is relative, it is assumed to be relative to this cache's
221  /// root layer. See documentation on RequestLayerMuting for
222  /// more details.
223  PCP_API
224  bool IsLayerMuted(const std::string& layerIdentifier) const;
225 
226  /// Returns true if the layer specified by \p layerIdentifier is
227  /// muted in this cache, false otherwise. If \p layerIdentifier
228  /// is relative, it is assumed to be relative to \p anchorLayer.
229  /// If \p canonicalMutedLayerIdentifier is supplied, it will be
230  /// populated with the canonical identifier of the muted layer if this
231  /// function returns true. See documentation on RequestLayerMuting
232  /// for more details.
233  PCP_API
234  bool IsLayerMuted(const SdfLayerHandle& anchorLayer,
235  const std::string& layerIdentifier,
236  std::string* canonicalMutedLayerIdentifier
237  = nullptr) const;
238 
239  /// Returns parameter object containing all inputs for the prim index
240  /// computation used by this cache.
241  ///
242  /// Note that this inputs object holds raw pointers to internal objects
243  /// within this cache as well as a raw pointer to the cache itself. In other
244  /// words, even if a copy is made of this inputs structure, it still may
245  /// only be used within the lifetime of this cache.
246  PCP_API
247  const PcpPrimIndexInputs &GetPrimIndexInputs() const;
248 
249  /// @}
250 
251  /// \name Computations
252  /// @{
253 
254  /// Returns the layer stack for \p identifier if it exists, otherwise
255  /// creates a new layer stack for \p identifier. This returns \c NULL
256  /// if \p identifier is invalid (i.e. its root layer is \c NULL).
257  /// \p allErrors will contain any errors encountered while creating a
258  /// new layer stack. It'll be unchanged if the layer stack already existed.
259  PCP_API
260  PcpLayerStackRefPtr
261  ComputeLayerStack(const PcpLayerStackIdentifier &identifier,
262  PcpErrorVector *allErrors);
263 
264  /// Returns the layer stack for \p identifier if it has been computed
265  /// and cached, otherwise returns \c NULL.
266  PCP_API
267  PcpLayerStackPtr
268  FindLayerStack(const PcpLayerStackIdentifier &identifier) const;
269 
270  /// Return true if \p layerStack is used by this cache in its composition,
271  /// false otherwise.
272  PCP_API
273  bool UsesLayerStack(const PcpLayerStackPtr &layerStack) const;
274 
275  /// Compute and return a reference to the cached result for the
276  /// prim index for the given path. \p allErrors will contain any errors
277  /// encountered while performing this operation.
278  PCP_API
279  const PcpPrimIndex &
280  ComputePrimIndex(const SdfPath &primPath, PcpErrorVector *allErrors);
281 
282  /// Compute PcpPrimIndexes in the subtree rooted at path in parallel,
283  /// recursing to children based on the supplied \p childrenPred. Also
284  /// include payloads not already in this cache's included payloads (see
285  /// GetIncludedPayloads()) according to \p payloadPred.
286  ///
287  /// This is similar to ComputePrimIndex(), except it computes an entire
288  /// subtree of indexes in parallel so it can be much more efficient. This
289  /// function invokes both \p childrenPred and \p payloadPred concurrently,
290  /// so it must be safe to do so.
291  ///
292  /// When a PcpPrimIndex computation completes invoke \p childrenPred,
293  /// passing it the PcpPrimIndex. If \p childrenPred returns true, continue
294  /// indexing children prim indexes. In this case, \p childrenPred may
295  /// provide a list of names of the children prim indexes to compute.
296  /// If it does not, all children prim indexes will be computed.
297  /// If \p childrenPred returns false, stop indexing in that subtree.
298  ///
299  /// If payloads discovered during indexing do not already appear in this
300  /// cache's set of included payloads, invoke \p payloadPred, passing it the
301  /// path for the prim with the payload. If \p payloadPred returns true,
302  /// include its payload and add it to the cache's set of included payloads
303  /// upon completion.
304  template <class ChildrenPredicate, class PayloadPredicate>
306  PcpErrorVector *allErrors,
307  const ChildrenPredicate &childrenPred,
308  const PayloadPredicate &payloadPred) {
309  ComputePrimIndexesInParallel(SdfPathVector(1, path), allErrors,
310  childrenPred, payloadPred,
311  "Pcp", "ComputePrimIndexesInParallel");
312  }
313 
314  /// \overload
315  /// XXX Do not add new callers of this method. It is needed as a workaround
316  /// for bug #132031, which we hope to tackle soon (as of 6/2016)
317  template <class ChildrenPredicate, class PayloadPredicate>
319  PcpErrorVector *allErrors,
320  const ChildrenPredicate &childrenPred,
321  const PayloadPredicate &payloadPred,
322  const char *mallocTag1,
323  const char *mallocTag2) {
324  ComputePrimIndexesInParallel(SdfPathVector(1, path), allErrors,
325  childrenPred, payloadPred,
326  mallocTag1, mallocTag2);
327  }
328 
329  /// Vectorized form of ComputePrimIndexesInParallel(). Equivalent to
330  /// invoking that method for each path in \p paths, but more efficient.
331  template <class ChildrenPredicate, class PayloadPredicate>
333  PcpErrorVector *allErrors,
334  const ChildrenPredicate &childrenPred,
335  const PayloadPredicate &payloadPred) {
336  _UntypedIndexingChildrenPredicate cp(&childrenPred);
337  _UntypedIndexingPayloadPredicate pp(&payloadPred);
338  _ComputePrimIndexesInParallel(paths, allErrors, cp, pp,
339  "Pcp", "ComputePrimIndexesInParallel");
340  }
341 
342  /// \overload
343  /// XXX Do not add new callers of this method. It is needed as a workaround
344  /// for bug #132031, which we hope to tackle soon (as of 6/2016)
345  template <class ChildrenPredicate, class PayloadPredicate>
347  PcpErrorVector *allErrors,
348  const ChildrenPredicate &childrenPred,
349  const PayloadPredicate &payloadPred,
350  const char *mallocTag1,
351  const char *mallocTag2) {
352  _UntypedIndexingChildrenPredicate cp(&childrenPred);
353  _UntypedIndexingPayloadPredicate pp(&payloadPred);
354  _ComputePrimIndexesInParallel(paths, allErrors, cp, pp,
355  mallocTag1, mallocTag2);
356  }
357 
358  /// Returns a pointer to the cached computed prim index for the given
359  /// path, or NULL if it has not been computed.
360  PCP_API
361  const PcpPrimIndex *
362  FindPrimIndex(const SdfPath &primPath) const;
363 
364  /// Run the given \p callback on every prim index in the cache.
365  /// The callback must have the signature: void(const PcpPrimIndex&).
366  template <class Callback>
367  void
368  ForEachPrimIndex(const Callback& callback) const
369  {
371  _ForEachPrimIndex(fn);
372  }
373 
374  /// Compute and return a reference to the cached result for the
375  /// property index for the given path. \p allErrors will contain any
376  /// errors encountered while performing this operation.
377  PCP_API
378  const PcpPropertyIndex &
379  ComputePropertyIndex(const SdfPath &propPath, PcpErrorVector *allErrors);
380 
381  /// Returns a pointer to the cached computed property index for the given
382  /// path, or NULL if it has not been computed.
383  PCP_API
384  const PcpPropertyIndex *
385  FindPropertyIndex(const SdfPath &propPath) const;
386 
387  /// Compute the relationship target paths for the relationship at
388  /// \p relationshipPath into \p paths. If \p localOnly is \c true then
389  /// this will compose relationship targets from local nodes only. If
390  /// \p stopProperty is not \c NULL then this will stop composing
391  /// relationship targets at \p stopProperty, including \p stopProperty
392  /// iff \p includeStopProperty is \c true. If not \c NULL, \p deletedPaths
393  /// will be populated with target paths whose deletion contributed to
394  /// the computed result. \p allErrors will contain any errors encountered
395  /// while performing this operation.
396  PCP_API
397  void
398  ComputeRelationshipTargetPaths(const SdfPath &relationshipPath,
399  SdfPathVector *paths,
400  bool localOnly,
401  const SdfSpecHandle &stopProperty,
402  bool includeStopProperty,
403  SdfPathVector *deletedPaths,
404  PcpErrorVector *allErrors);
405 
406  /// Compute the attribute connection paths for the attribute at
407  /// \p attributePath into \p paths. If \p localOnly is \c true then
408  /// this will compose attribute connections from local nodes only. If
409  /// \p stopProperty is not \c NULL then this will stop composing
410  /// attribute connections at \p stopProperty, including \p stopProperty
411  /// iff \p includeStopProperty is \c true. If not \c NULL, \p deletedPaths
412  /// will be populated with connection paths whose deletion contributed to
413  /// the computed result. \p allErrors will contain any errors encountered
414  /// while performing this operation.
415  PCP_API
416  void
417  ComputeAttributeConnectionPaths(const SdfPath &attributePath,
418  SdfPathVector *paths,
419  bool localOnly,
420  const SdfSpecHandle &stopProperty,
421  bool includeStopProperty,
422  SdfPathVector *deletedPaths,
423  PcpErrorVector *allErrors);
424 
425  /// @}
426  /// \name Dependencies
427  /// @{
428 
429  /// Returns set of all layers used by this cache.
430  PCP_API
432 
433  /// Return a number that can be used to determine whether or not the set of
434  /// layers used by this cache may have changed or not. For example, if one
435  /// calls GetUsedLayers() and saves the GetUsedLayersRevision(), and then
436  /// later calls GetUsedLayersRevision() again, if the number is unchanged,
437  /// then GetUsedLayers() is guaranteed to be unchanged as well.
438  PCP_API
439  size_t GetUsedLayersRevision() const;
440 
441  /// Returns set of all root layers used by this cache.
442  PCP_API
444 
445  /// Returns every computed & cached layer stack that includes \p layer.
446  PCP_API
447  const PcpLayerStackPtrVector&
448  FindAllLayerStacksUsingLayer(const SdfLayerHandle& layer) const;
449 
450  /// Run the given \p callbcack on every layer stack used by prim
451  /// indexes in the cache. The callback must have the signature:
452  /// void(const PcpLayerStackPtr&).
453  template <class Callback>
454  void
455  ForEachLayerStack(const Callback& callback) const
456  {
458  _ForEachLayerStack(fn);
459  }
460 
461  /// Returns dependencies on the given site of scene description,
462  /// as discovered by the cached index computations.
463  ///
464  /// \param depMask specifies what classes of dependency to include;
465  /// see PcpDependencyFlags for details
466  /// \param recurseOnSite includes incoming dependencies on
467  /// children of sitePath
468  /// \param recurseOnIndex extends the result to include all PcpCache
469  /// child indexes below discovered results
470  /// \param filterForExistingCachesOnly filters the results to only
471  /// paths representing computed prim and property index caches;
472  /// otherwise a recursively-expanded result can include
473  /// un-computed paths that are expected to depend on the site
474  PCP_API
476  FindSiteDependencies(const PcpLayerStackPtr& siteLayerStack,
477  const SdfPath& sitePath,
478  PcpDependencyFlags depMask,
479  bool recurseOnSite,
480  bool recurseOnIndex,
481  bool filterForExistingCachesOnly) const;
482 
483  /// Returns dependencies on the given site of scene description,
484  /// as discovered by the cached index computations.
485  ///
486  /// This method overload takes a site layer rather than a layer
487  /// stack. It will check every layer stack using that layer, and
488  /// apply any relevant sublayer offsets to the map functions in the
489  /// returned PcpDependencyVector.
490  ///
491  /// See the other method for parameter details.
492  PCP_API
494  FindSiteDependencies(const SdfLayerHandle& siteLayer,
495  const SdfPath& sitePath,
496  PcpDependencyFlags depMask,
497  bool recurseOnSite,
498  bool recurseOnIndex,
499  bool filterForExistingCachesOnly) const;
500 
501  /// Returns \c true if an opinion for the site at \p localPcpSitePath
502  /// in the cache's layer stack can be provided by an opinion in \p layer,
503  /// \c false otherwise. If \c true and \p allowedPathInLayer is not
504  /// \c NULL then it's set to a path in \p layer that would provide an
505  /// opinion.
506  ///
507  /// This returns \c false if no prim index has yet been computed for
508  /// \p localPcpSitePath.
509  PCP_API
510  bool CanHaveOpinionForSite(const SdfPath& localPcpSitePath,
511  const SdfLayerHandle& layer,
512  SdfPath* allowedPathInLayer) const;
513 
514  /// Returns a vector of sublayer asset paths used in the layer stack
515  /// that didn't resolve to valid assets.
516  PCP_API
517  std::vector<std::string> GetInvalidSublayerIdentifiers() const;
518 
519  /// Returns true if \p identifier was used as a sublayer path in a
520  /// layer stack but did not identify a valid layer. This is functionally
521  /// equivalent to examining the values in the vector returned by
522  /// GetInvalidSublayerIdentifiers, but more efficient.
523  PCP_API
524  bool IsInvalidSublayerIdentifier(const std::string& identifier) const;
525 
526  /// Returns a map of prim paths to asset paths used by that prim
527  /// (e.g. in a reference) that didn't resolve to valid assets.
528  PCP_API
529  std::map<SdfPath, std::vector<std::string>, SdfPath::FastLessThan>
530  GetInvalidAssetPaths() const;
531 
532  /// Returns true if \p resolvedAssetPath was used by a prim (e.g. in
533  /// a reference) but did not resolve to a valid asset. This is
534  /// functionally equivalent to examining the values in the map returned
535  /// by GetInvalidAssetPaths, but more efficient.
536  PCP_API
537  bool IsInvalidAssetPath(const std::string& resolvedAssetPath) const;
538 
539  /// Returns true if any prim index in this cache has a dependency on a
540  /// dynamic file format argument field.
541  PCP_API
543 
544  /// Returns true if any prim index in this cache has a dependency on a
545  /// dynamic file format argument attribute's default value field.
546  PCP_API
548 
549  /// Returns true if the given \p field is the name of a field that
550  /// was composed while generating dynamic file format arguments for any prim
551  /// index in this cache.
552  PCP_API
553  bool IsPossibleDynamicFileFormatArgumentField(const TfToken &field) const;
554 
555  /// Returns true if the given \p attributeName is the name of an attribute
556  /// whose default value field was composed while generating dynamic file
557  /// format arguments for any prim index in this cache.
558  PCP_API
560  const TfToken &attributeName) const;
561 
562  /// Returns the dynamic file format dependency data object for the prim
563  /// index with the given \p primIndexPath. This will return an empty
564  /// dependency data if either there is no cache prim index for the path or
565  /// if the prim index has no dynamic file formats that it depends on.
566  PCP_API
569  const SdfPath &primIndexPath) const;
570 
571  /// Returns the list of prim index paths that depend on one or more
572  /// expression variables from \p layerStack.
573  PCP_API
575  const PcpLayerStackPtr &layerStack) const;
576 
577  /// Returns the set of expression variables in \p layerStack that are
578  /// used by the prim index at \p primIndexPath.
579  PCP_API
580  const std::unordered_set<std::string>&
582  const SdfPath &primIndexPath,
583  const PcpLayerStackPtr &layerStack) const;
584 
585  /// @}
586 
587  /// \name Change handling
588  /// @{
589 
590  /// Apply the changes in \p changes. This blows caches. It's up to
591  /// the client to pull on those caches again as needed.
592  ///
593  /// Objects that are no longer needed and would be destroyed are
594  /// retained in \p lifeboat and won't be destroyed until \p lifeboat is
595  /// itself destroyed. This gives the client control over the timing
596  /// of the destruction of those objects. Clients may choose to pull
597  /// on the caches before destroying \p lifeboat. That may cause the
598  /// caches to again retain the objects, meaning they won't be destroyed
599  /// when \p lifeboat is destroyed.
600  ///
601  /// For example, if blowing a cache means an SdfLayer is no longer
602  /// needed then \p lifeboat will hold an SdfLayerRefPtr to that layer.
603  /// The client can then pull on that cache, which could cause the
604  /// cache to hold an SdfLayerRefPtr to the layer again. If so then
605  /// destroying \p changes will not destroy the layer. In any case,
606  /// we don't destroy the layer and then read it again. However, if
607  /// the client destroys \p lifeboat before pulling on the cache then
608  /// we would destroy the layer then read it again.
609  PCP_API
610  void Apply(const PcpCacheChanges& changes, PcpLifeboat* lifeboat);
611 
612  /// Reload the layers of the layer stack, except session layers
613  /// and sublayers of session layers. This will also try to load
614  /// sublayers in this cache's layer stack that could not be loaded
615  /// previously. It will also try to load any referenced or payloaded
616  /// layer that could not be loaded previously. Clients should
617  /// subsequently \c Apply() \p changes to use any now-valid layers.
618  PCP_API
619  void Reload(PcpChanges* changes);
620 
621  /// Reload every layer used by the prim at \p primPath that's across
622  /// a reference or payload. Clients should subsequently apply the
623  /// changes to use any now valid layers.
624  ///
625  /// Note: If a reference or payload was to an invalid asset and this
626  /// asset is valid upon reloading then this call will not necessarily
627  /// reload every layer accessible across the reference or payload.
628  /// For example, say prim R has an invalid reference and prim Q has a
629  /// valid reference to layer X with sublayer Y. If on reload R now
630  /// has a valid reference to layer Z with sublayer Y, we will load Z
631  /// but we will not reload Y.
632  PCP_API
633  void ReloadReferences(PcpChanges* changes, const SdfPath& primPath);
634 
635  /// @}
636 
637  /// \name Diagnostics
638  /// @{
639 
640  /// Prints various statistics about the data stored in this cache.
641  PCP_API
642  void PrintStatistics() const;
643 
644  /// @}
645 
646 private:
647  friend class PcpChanges;
648  friend class Pcp_Dependencies;
649  friend class Pcp_Statistics;
650 
651  struct _ParallelIndexer;
652 
653  // Helper struct to type-erase a children predicate for the duration of
654  // ComputePrimIndexesInParallel.
655  //
656  // This lets us achieve two goals. First, clients may pass any arbitrary
657  // type as a predicate (e.g. they do not have to derive some base class).
658  // Second, it lets us keep the parallel indexing implementation in the .cpp
659  // file, avoiding any large template code instantiation.
660  //
661  // The cost we pay is this very thin indirect call. We instantiate a
662  // function template with the client's predicate type that simply does a
663  // typecast and predicate invocation, and pass that function pointer into
664  // the implementation. There is no heap allocation, no predicate copy, no
665  // argument marshalling, etc.
666  struct _UntypedIndexingChildrenPredicate {
667  _UntypedIndexingChildrenPredicate() : pred(nullptr), invoke(nullptr) {}
668  template <class Pred>
669  explicit _UntypedIndexingChildrenPredicate(const Pred *pred)
670  : pred(pred), invoke(_Invoke<Pred>) {}
671 
672  inline bool operator()(const PcpPrimIndex &index,
673  TfTokenVector *childNamesToCompose) const {
674  return invoke(pred, index, childNamesToCompose);
675  }
676  private:
677  template <class Pred>
678  static bool _Invoke(const void *pred, const PcpPrimIndex &index,
679  TfTokenVector *namesToCompose) {
680  return (*static_cast<const Pred *>(pred))(index, namesToCompose);
681  }
682  const void *pred;
683  bool (*invoke)(const void *, const PcpPrimIndex &, TfTokenVector *);
684  };
685 
686  // See doc for _UntypedIndexingChildrenPredicate above. This does the same
687  // for the payload inclusion predicate.
688  struct _UntypedIndexingPayloadPredicate {
689  template <class Pred>
690  explicit _UntypedIndexingPayloadPredicate(const Pred *pred)
691  : pred(pred), invoke(_Invoke<Pred>) {}
692 
693  inline bool operator()(const SdfPath &path) const {
694  return invoke(pred, path);
695  }
696  private:
697  template <class Pred>
698  static bool _Invoke(const void *pred, const SdfPath &path) {
699  return (*static_cast<const Pred *>(pred))(path);
700  }
701  const void *pred;
702  bool (*invoke)(const void *, const SdfPath &);
703  };
704 
705  // Internal helper for recursive indexing.
706  const PcpPrimIndex &
707  _ComputePrimIndexWithCompatibleInputs(
708  const SdfPath & path, const PcpPrimIndexInputs &inputs,
709  PcpErrorVector *allErrors);
710 
711  // Friend to allow low-level indexing code access to the above.
712  friend const PcpPrimIndex &
714  PcpCache &cache,
715  const SdfPath & path, const PcpPrimIndexInputs &inputs,
716  PcpErrorVector *allErrors);
717 
718  // Parallel indexing implementation.
719  PCP_API
720  void _ComputePrimIndexesInParallel(
721  const SdfPathVector &paths,
722  PcpErrorVector *allErrors,
723  _UntypedIndexingChildrenPredicate childrenPred,
724  _UntypedIndexingPayloadPredicate payloadPred,
725  const char *mallocTag1,
726  const char *mallocTag2);
727 
728  void _RemovePrimCache(const SdfPath& primPath, PcpLifeboat* lifeboat);
729  void _RemovePrimAndPropertyCaches(const SdfPath& root,
730  PcpLifeboat* lifeboat);
731  void _RemovePropertyCache(const SdfPath& root, PcpLifeboat* lifeboat);
732  void _RemovePropertyCaches(const SdfPath& root, PcpLifeboat* lifeboat);
733 
734  // Returns the prim index for \p path if it exists, NULL otherwise.
735  PcpPrimIndex* _GetPrimIndex(const SdfPath& path);
736  const PcpPrimIndex* _GetPrimIndex(const SdfPath& path) const;
737 
738  // Returns the property index for \p path if it exists, NULL otherwise.
739  PcpPropertyIndex* _GetPropertyIndex(const SdfPath& path);
740  const PcpPropertyIndex* _GetPropertyIndex(const SdfPath& path) const;
741 
742  PCP_API
743  void _ForEachPrimIndex(
744  const TfFunctionRef<void(const PcpPrimIndex&)>& fn) const;
745 
746  PCP_API
747  void _ForEachLayerStack(
748  const TfFunctionRef<void(const PcpLayerStackPtr&)>& fn) const;
749 
750 private:
751  // Fixed evaluation parameters, set when the cache is created. Note that
752  // _rootLayer and _sessionLayer are not const because we want to mutate them
753  // to enable parallel teardown in the destructor.
754  SdfLayerRefPtr _rootLayer;
755  SdfLayerRefPtr _sessionLayer;
756  const PcpLayerStackIdentifier _layerStackIdentifier;
757 
758  // Flag that configures PcpCache to use the restricted set of USD features.
759  // Currently it governs whether relocates, inherits, permissions,
760  // symmetry, or payloads are considered, and whether the prim stack
761  // is populated and its depdencies gathered during computation of
762  // prim indices and composition of prim child names.
763  const bool _usd;
764 
765  // File format target for all scene description layers this cache will
766  // find or open during prim index computation.
767  const std::string _fileFormatTarget;
768 
769  // The layer stack for this cache. Holding this by ref ptr means we
770  // hold all of our local layers by ref ptr (including the root and
771  // session layers, again).
772  PcpLayerStackRefPtr _layerStack;
773 
774  // Modifiable evaluation parameters.
775  // Anything that changes these should also yield a PcpChanges
776  // value describing the necessary cache invalidation.
777  PayloadSet _includedPayloads;
778  PcpVariantFallbackMap _variantFallbackMap;
779 
780  // The default prim index inputs used when computing a prim index within
781  // this cache.
782  PcpPrimIndexInputs _primIndexInputs;
783 
784  // Cached computation types.
785  typedef Pcp_LayerStackRegistryRefPtr _LayerStackCache;
786  typedef SdfPathTable<PcpPrimIndex> _PrimIndexCache;
787  typedef SdfPathTable<PcpPropertyIndex> _PropertyIndexCache;
788 
789  // Cached computations.
790  _LayerStackCache _layerStackCache;
791  _PrimIndexCache _primIndexCache;
792  _PropertyIndexCache _propertyIndexCache;
793  std::unique_ptr<Pcp_Dependencies> _primDependencies;
794 
795  // Parallel indexer state.
796  std::unique_ptr<_ParallelIndexer> _parallelIndexer;
797 };
798 
800 
801 #endif // PXR_USD_PCP_CACHE_H
PCP_API bool CanHaveOpinionForSite(const SdfPath &localPcpSitePath, const SdfLayerHandle &layer, SdfPath *allowedPathInLayer) const
std::vector< PcpDependency > PcpDependencyVector
Definition: dependency.h:115
void ComputePrimIndexesInParallel(const SdfPathVector &paths, PcpErrorVector *allErrors, const ChildrenPredicate &childrenPred, const PayloadPredicate &payloadPred)
Definition: cache.h:332
PCP_API bool IsPayloadIncluded(const SdfPath &path) const
Return true if the payload is included for the given path.
PCP_API void Reload(PcpChanges *changes)
PCP_API bool IsLayerMuted(const std::string &layerIdentifier) const
PCP_API bool HasAnyDynamicFileFormatArgumentFieldDependencies() const
PCP_API const PcpPropertyIndex & ComputePropertyIndex(const SdfPath &propPath, PcpErrorVector *allErrors)
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
PCP_API const std::string & GetFileFormatTarget() const
Returns the file format target this cache is configured for.
PCP_API PcpDependencyVector FindSiteDependencies(const PcpLayerStackPtr &siteLayerStack, const SdfPath &sitePath, PcpDependencyFlags depMask, bool recurseOnSite, bool recurseOnIndex, bool filterForExistingCachesOnly) const
PCP_API ~PcpCache()
Definition: cache.h:76
Definition: spec.h:32
PCP_API SdfLayerHandleSet GetUsedRootLayers() const
Returns set of all root layers used by this cache.
std::set< SdfHandleTo< SdfLayer >::Handle > SdfLayerHandleSet
PCP_API bool IsUsd() const
Return true if the cache is configured in Usd mode.
PCP_API bool HasAnyDynamicFileFormatArgumentAttributeDependencies() const
PCP_API const std::vector< std::string > & GetMutedLayers() const
PCP_API const PcpPrimIndex & ComputePrimIndex(const SdfPath &primPath, PcpErrorVector *allErrors)
PCP_API std::vector< std::string > GetInvalidSublayerIdentifiers() const
void ComputePrimIndexesInParallel(const SdfPath &path, PcpErrorVector *allErrors, const ChildrenPredicate &childrenPred, const PayloadPredicate &payloadPred, const char *mallocTag1, const char *mallocTag2)
Definition: cache.h:318
OutGridT const XformOp bool bool
PCP_API const PcpDynamicFileFormatDependencyData & GetDynamicFileFormatArgumentDependencyData(const SdfPath &primIndexPath) const
GLenum GLuint GLint GLint layer
Definition: glcorearb.h:1299
PCP_API bool IsInvalidAssetPath(const std::string &resolvedAssetPath) const
friend const PcpPrimIndex & Pcp_ComputePrimIndexWithCompatibleInputs(PcpCache &cache, const SdfPath &path, const PcpPrimIndexInputs &inputs, PcpErrorVector *allErrors)
void ComputePrimIndexesInParallel(const SdfPathVector &paths, PcpErrorVector *allErrors, const ChildrenPredicate &childrenPred, const PayloadPredicate &payloadPred, const char *mallocTag1, const char *mallocTag2)
Definition: cache.h:346
PCP_API const SdfPathVector & GetPrimsUsingExpressionVariablesFromLayerStack(const PcpLayerStackPtr &layerStack) const
PCP_API void ComputeAttributeConnectionPaths(const SdfPath &attributePath, SdfPathVector *paths, bool localOnly, const SdfSpecHandle &stopProperty, bool includeStopProperty, SdfPathVector *deletedPaths, PcpErrorVector *allErrors)
Definition: token.h:70
PCP_API const PcpPropertyIndex * FindPropertyIndex(const SdfPath &propPath) const
std::vector< class SdfPath > SdfPathVector
PCP_API size_t GetUsedLayersRevision() const
PCP_API void Apply(const PcpCacheChanges &changes, PcpLifeboat *lifeboat)
std::unordered_set< SdfPath, SdfPath::Hash > PayloadSet
Returns the payloads requested for inclusion.
Definition: cache.h:153
PCP_API PcpLayerStackRefPtr ComputeLayerStack(const PcpLayerStackIdentifier &identifier, PcpErrorVector *allErrors)
PCP_API void RequestPayloads(const SdfPathSet &pathsToInclude, const SdfPathSet &pathsToExclude, PcpChanges *changes=NULL)
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:440
PCP_API void ReloadReferences(PcpChanges *changes, const SdfPath &primPath)
friend class Pcp_Statistics
Definition: cache.h:649
PCP_API const PcpLayerStackPtrVector & FindAllLayerStacksUsingLayer(const SdfLayerHandle &layer) const
Returns every computed & cached layer stack that includes layer.
PCP_API bool IsInvalidSublayerIdentifier(const std::string &identifier) const
SDF_DECLARE_HANDLES(SdfSpec)
Definition: path.h:273
PCP_API PcpLayerStackPtr GetLayerStack() const
PCP_API const std::unordered_set< std::string > & GetExpressionVariablesFromLayerStackUsedByPrim(const SdfPath &primIndexPath, const PcpLayerStackPtr &layerStack) const
PCP_API PcpLayerStackPtr FindLayerStack(const PcpLayerStackIdentifier &identifier) const
PCP_API const PcpPrimIndexInputs & GetPrimIndexInputs() const
std::vector< PcpErrorBasePtr > PcpErrorVector
Definition: errors.h:65
PCP_API const PcpPrimIndex * FindPrimIndex(const SdfPath &primPath) const
PCP_API void SetVariantFallbacks(const PcpVariantFallbackMap &map, PcpChanges *changes=NULL)
std::set< class SdfPath > SdfPathSet
A set of SdfPaths.
Definition: path.h:192
PCP_API std::map< SdfPath, std::vector< std::string >, SdfPath::FastLessThan > GetInvalidAssetPaths() const
friend class Pcp_Dependencies
Definition: cache.h:648
TF_DECLARE_WEAK_AND_REF_PTRS(PcpLayerStack)
void ForEachPrimIndex(const Callback &callback) const
Definition: cache.h:368
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
PCP_API PcpVariantFallbackMap GetVariantFallbacks() const
PCP_API SdfLayerHandleSet GetUsedLayers() const
Returns set of all layers used by this cache.
GLuint index
Definition: glcorearb.h:786
bool HasRootLayerStack(PcpLayerStackRefPtr const &layerStack) const
Definition: cache.h:117
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
PCP_API const PcpLayerStackIdentifier & GetLayerStackIdentifier() const
Get the identifier of the layerStack used for composition.
PCP_API bool IsPossibleDynamicFileFormatArgumentField(const TfToken &field) const
void ComputePrimIndexesInParallel(const SdfPath &path, PcpErrorVector *allErrors, const ChildrenPredicate &childrenPred, const PayloadPredicate &payloadPred)
Definition: cache.h:305
PCP_API void RequestLayerMuting(const std::vector< std::string > &layersToMute, const std::vector< std::string > &layersToUnmute, PcpChanges *changes=nullptr, std::vector< std::string > *newLayersMuted=nullptr, std::vector< std::string > *newLayersUnmuted=nullptr)
void ForEachLayerStack(const Callback &callback) const
Definition: cache.h:455
PCP_API void ComputeRelationshipTargetPaths(const SdfPath &relationshipPath, SdfPathVector *paths, bool localOnly, const SdfSpecHandle &stopProperty, bool includeStopProperty, SdfPathVector *deletedPaths, PcpErrorVector *allErrors)
PCP_API bool IsPossibleDynamicFileFormatArgumentAttribute(const TfToken &attributeName) const
PCP_API PayloadSet const & GetIncludedPayloads() const
Returns the payloads requested for inclusion.
unsigned int PcpDependencyFlags
A typedef for a bitmask of flags from PcpDependencyType.
Definition: dependency.h:92
PCP_API void PrintStatistics() const
Prints various statistics about the data stored in this cache.
std::map< std::string, std::vector< std::string > > PcpVariantFallbackMap
Definition: types.h:189
PCP_API bool UsesLayerStack(const PcpLayerStackPtr &layerStack) const
int invoke(const Func &taskFunc1, Rest...taskFuncN)
Definition: Invoke.h:64
#define PCP_API
Definition: api.h:23