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