This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
primIndex.h
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_PRIM_INDEX_H
8#define PXR_USD_PCP_PRIM_INDEX_H
9
10#include "pxr/pxr.h"
11#include "pxr/usd/pcp/api.h"
13#include "pxr/usd/pcp/dependency.h"
14#include "pxr/usd/pcp/dynamicFileFormatDependencyData.h"
15#include "pxr/usd/pcp/expressionVariablesDependencyData.h"
16#include "pxr/usd/pcp/errors.h"
17#include "pxr/usd/pcp/iterator.h"
18#include "pxr/usd/pcp/node.h"
19#include "pxr/usd/pcp/types.h"
21#include "pxr/usd/sdf/site.h"
23#include "pxr/base/tf/hashmap.h"
24#include "pxr/base/tf/hashset.h"
25
26#include <tbb/spin_rw_mutex.h>
27
28#include <functional>
29#include <map>
30#include <memory>
31#include <unordered_set>
32
33PXR_NAMESPACE_OPEN_SCOPE
34
35SDF_DECLARE_HANDLES(SdfLayer);
36SDF_DECLARE_HANDLES(SdfPrimSpec);
37
39TF_DECLARE_WEAK_AND_REF_PTRS(PcpPrimIndex_Graph);
40
41class ArResolver;
42class PcpCache;
43class PcpCacheChanges;
44class PcpPrimIndex;
47class SdfPath;
48
62{
63public:
65 PCP_API
67
69 PCP_API
71
73 PcpPrimIndex(PcpPrimIndex &&rhs) noexcept = default;
74
77 PcpPrimIndex(rhs).Swap(*this);
78 return *this;
79 }
80
81 // Move-assignment.
82 PcpPrimIndex &operator=(PcpPrimIndex &&rhs) noexcept = default;
83
85 PCP_API
86 void Swap(PcpPrimIndex& rhs);
87
89 inline void swap(PcpPrimIndex &rhs) { Swap(rhs); }
90
93 bool IsValid() const { return bool(_graph); }
94
95 void SetGraph(const PcpPrimIndex_GraphRefPtr& graph) {
96 _graph = graph;
97 }
98
108 const PcpArc &arcToParent,
109 PcpPrimIndex &&childPrimIndex,
110 PcpErrorBasePtr *error);
111
112 const PcpPrimIndex_GraphRefPtr &GetGraph() const {
113 return _graph;
114 }
115
117 PCP_API
119
122 PCP_API
123 const SdfPath& GetPath() const;
124
127 PCP_API
128 bool HasSpecs() const;
129
134 PCP_API
135 bool HasAnyPayloads() const;
136
139 PCP_API
140 bool IsUsd() const;
141
147 PCP_API
148 bool IsInstanceable() const;
149
152
158 PCP_API
159 PcpNodeRange GetNodeRange(PcpRangeType rangeType = PcpRangeTypeAll) const;
160
165 PCP_API
167
170 PCP_API
171 PcpNodeRange GetNodeSubtreeRange(const PcpNodeRef &node) const;
172
175 PCP_API
176 PcpPrimRange GetPrimRange(PcpRangeType rangeType = PcpRangeTypeAll) const;
177
180 PCP_API
181 PcpPrimRange GetPrimRangeForNode(const PcpNodeRef& node) const;
182
184
187
190 PCP_API
191 PcpNodeRef GetNodeProvidingSpec(const SdfPrimSpecHandle& primSpec) const;
192
196 PCP_API
198 const SdfLayerHandle& layer, const SdfPath& path) const;
199
201
204
206 PcpErrorVector GetLocalErrors() const {
207 return _localErrors ? *_localErrors.get() : PcpErrorVector();
208 }
209
211 PCP_API
212 void PrintStatistics() const;
213
220 PCP_API
221 std::string DumpToString(
222 bool includeInheritOriginInfo = true,
223 bool includeMaps = true) const;
224
227 PCP_API
229 const std::string& filename,
230 bool includeInheritOriginInfo = true,
231 bool includeMaps = false) const;
232
234
235
238
241 PCP_API
243 PcpTokenSet *prohibitedNameSet) const;
244
247 PCP_API
249 const PcpNodeRef &subtreeRootNode,
250 TfTokenVector *nameOrder,
251 PcpTokenSet *prohibitedNameSet) const;
252
256 PCP_API
258
266 PCP_API
268
273 PCP_API
275 const std::string &variantSet) const;
276
278
279private:
280 friend class PcpPrimIterator;
281 friend struct Pcp_PrimIndexer;
282 friend void Pcp_RescanForSpecs(
283 PcpPrimIndex*, bool usd,
284 bool updateHasSpecs,
285 const PcpCacheChanges *cacheChanges);
286
287 // The node graph representing the compositional structure of this prim.
288 PcpPrimIndex_GraphRefPtr _graph;
289
290 // The prim stack. This is just a derived structure representing
291 // a cached strong-to-weak traversal of the graph collecting specs.
292 Pcp_CompressedSdSiteVector _primStack;
293
294 // List of errors local to this prim, encountered during computation.
295 // NULL if no errors were found (the expected common case).
296 std::unique_ptr<PcpErrorVector> _localErrors;
297};
298
300inline void swap(PcpPrimIndex &l, PcpPrimIndex &r) { l.swap(r); }
301
307{
308public:
313 enum PayloadState { NoPayload,
314 IncludedByIncludeSet, ExcludedByIncludeSet,
315 IncludedByPredicate, ExcludedByPredicate };
316
320
322 PcpErrorVector allErrors;
323
327
333
337
339 std::vector<PcpCulledDependency> culledDependencies;
340
348 const PcpArc& arcToParent,
349 PcpErrorBasePtr *error);
350};
351
357public:
359 : cache(nullptr)
360 , variantFallbacks(nullptr)
361 , includedPayloads(nullptr)
362 , includedPayloadsMutex(nullptr)
363 , parentIndex(nullptr)
364 , cull(true)
365 , usd(false)
366 { }
367
370 bool IsEquivalentTo(const PcpPrimIndexInputs& params) const;
371
375 { cache = cache_; return *this; }
376
380 { variantFallbacks = map; return *this; }
381
384 using PayloadSet = std::unordered_set<SdfPath, SdfPath::Hash>;
385 PcpPrimIndexInputs& IncludedPayloads(const PayloadSet* payloadSet)
386 { includedPayloads = payloadSet; return *this; }
387
389 PcpPrimIndexInputs &IncludedPayloadsMutex(tbb::spin_rw_mutex *mutex)
390 { includedPayloadsMutex = mutex; return *this; }
391
397 std::function<bool (const SdfPath &)> predicate)
398 { includePayloadPredicate = predicate; return *this; }
399
402 PcpPrimIndexInputs& Cull(bool doCulling = true)
403 { cull = doCulling; return *this; }
404
408 PcpPrimIndexInputs& USD(bool doUSD = true)
409 { usd = doUSD; return *this; }
410
413 PcpPrimIndexInputs& FileFormatTarget(const std::string& target)
414 { fileFormatTarget = target; return *this; }
415
416// private:
417 PcpCache* cache;
418 const PcpVariantFallbackMap* variantFallbacks;
419 const PayloadSet* includedPayloads;
420 tbb::spin_rw_mutex *includedPayloadsMutex;
421 std::function<bool (const SdfPath &)> includePayloadPredicate;
422 const PcpPrimIndex *parentIndex;
423 std::string fileFormatTarget;
424 bool cull;
425 bool usd;
426};
427
430PCP_API
431void
432PcpComputePrimIndex(
433 const SdfPath& primPath,
434 const PcpLayerStackPtr& layerStack,
435 const PcpPrimIndexInputs& inputs,
436 PcpPrimIndexOutputs* outputs,
437 ArResolver* pathResolver = NULL);
438
440PCP_API
441bool
442PcpIsNewDefaultStandinBehaviorEnabled();
443
444// Returns true if \p index should be recomputed due to changes to
445// any computed asset paths that were used to find or open layers
446// when originally composing \p index. This may be due to scene
447// description changes or external changes to asset resolution that
448// may affect the computation of those asset paths.
449bool
450Pcp_NeedToRecomputeDueToAssetPathChange(const PcpPrimIndex& index);
451
452PXR_NAMESPACE_CLOSE_SCOPE
453
454#endif // PXR_USD_PCP_PRIM_INDEX_H
Interface for the asset resolution system.
Definition: resolver.h:43
Represents an arc connecting two nodes in the prim index.
Definition: arc.h:28
Types of changes per cache.
Definition: changes.h:101
PcpCache is the context required to make requests of the Pcp composition algorithm and cache the resu...
Definition: cache.h:77
Contains the necessary information for storing a prim index's dependency on dynamic file format argum...
Captures the expression variables used by an associated prim index during composition.
Represents a stack of layers that contribute opinions to composition.
Definition: layerStack.h:50
Object used to iterate over nodes in the prim index graph in strong-to-weak order.
Definition: iterator.h:34
PcpNode represents a node in an expression tree for compositing scene description.
Definition: node.h:47
PcpPrimIndex is an index of the all sites of scene description that contribute opinions to a specific...
Definition: primIndex.h:62
PCP_API bool IsInstanceable() const
Returns true if this prim index is instanceable.
PCP_API std::string DumpToString(bool includeInheritOriginInfo=true, bool includeMaps=true) const
Dump the prim index contents to a string.
PCP_API PcpNodeRange GetNodeSubtreeRange(const PcpNodeRef &node) const
Returns range of iterators that encompass the given node and all of its descendants in strong-to-weak...
PCP_API PcpPrimRange GetPrimRangeForNode(const PcpNodeRef &node) const
Returns range of iterators that encompasses all prims from the site of node.
PcpPrimIndex(PcpPrimIndex &&rhs) noexcept=default
Move-construction.
void swap(PcpPrimIndex &rhs)
Same as Swap(), but standard name.
Definition: primIndex.h:89
PCP_API bool HasAnyPayloads() const
Returns true if the prim has any authored payload arcs.
PCP_API PcpPrimIndex()
Default construct an empty, invalid prim index.
PCP_API void ComputePrimPropertyNames(TfTokenVector *nameOrder) const
Compute the prim property names for the given path.
PCP_API PcpNodeRef GetRootNode() const
Returns the root node of the prim index graph.
PCP_API void DumpToDotGraph(const std::string &filename, bool includeInheritOriginInfo=true, bool includeMaps=false) const
Dump the prim index in dot format to the file named filename.
PCP_API void ComputePrimChildNames(TfTokenVector *nameOrder, PcpTokenSet *prohibitedNameSet) const
Compute the prim child names for the given path.
PCP_API PcpNodeRange GetNodeRange(PcpRangeType rangeType=PcpRangeTypeAll) const
Returns range of iterators that encompass all children of the root node with the given arc type as we...
PcpPrimIndex & operator=(const PcpPrimIndex &rhs)
Assignment.
Definition: primIndex.h:76
PCP_API void ComputePrimChildNamesInSubtree(const PcpNodeRef &subtreeRootNode, TfTokenVector *nameOrder, PcpTokenSet *prohibitedNameSet) const
Compute the prim child names for this prim when composed from only the subtree starting at subtreeRoo...
PCP_API SdfVariantSelectionMap ComposeAuthoredVariantSelections() const
Compose the authored prim variant selections.
PCP_API PcpNodeIterator GetNodeIteratorAtNode(const PcpNodeRef &node) const
Returns the node iterator that points to the given node if the node is in the prim index graph.
PcpNodeRef AddChildPrimIndex(const PcpArc &arcToParent, PcpPrimIndex &&childPrimIndex, PcpErrorBasePtr *error)
Add the nodes in childPrimIndex to this prim index; arcToParent specifies the node in this prim index...
PCP_API PcpNodeRef GetNodeProvidingSpec(const SdfLayerHandle &layer, const SdfPath &path) const
Returns the node that brings opinions from the Sd prim spec at layer and path into this prim index.
PCP_API PcpNodeRef GetNodeProvidingSpec(const SdfPrimSpecHandle &primSpec) const
Returns the node that brings opinions from primSpec into this prim index.
PcpErrorVector GetLocalErrors() const
Return the list of errors local to this prim.
Definition: primIndex.h:206
PCP_API bool IsUsd() const
Returns true if this prim index was composed in USD mode.
PCP_API PcpPrimIndex(const PcpPrimIndex &rhs)
Copy-construct a prim index.
PCP_API bool HasSpecs() const
Returns true if this prim index contains any scene description opinions.
PCP_API const SdfPath & GetPath() const
Returns the path of the prim whose opinions are represented by this prim index.
PCP_API std::string GetSelectionAppliedForVariantSet(const std::string &variantSet) const
Return the variant selection applied for the named variant set.
bool IsValid() const
Return true if this index is valid.
Definition: primIndex.h:93
PCP_API void PrintStatistics() const
Prints various statistics about this prim index.
PCP_API PcpPrimRange GetPrimRange(PcpRangeType rangeType=PcpRangeTypeAll) const
Returns range of iterators that encompasses all prims, in strong-to-weak order.
PCP_API void Swap(PcpPrimIndex &rhs)
Swap the contents of this prim index with index.
Inputs for the prim indexing procedure.
Definition: primIndex.h:356
std::unordered_set< SdfPath, SdfPath::Hash > PayloadSet
Set of paths to prims that should have their payloads included during composition.
Definition: primIndex.h:384
PcpPrimIndexInputs & VariantFallbacks(const PcpVariantFallbackMap *map)
Ordered list of variant names to use for the "standin" variant set if there is no authored opinion in...
Definition: primIndex.h:379
PcpPrimIndexInputs & Cull(bool doCulling=true)
Whether subtrees that contribute no opinions should be culled from the index.
Definition: primIndex.h:402
PcpPrimIndexInputs & Cache(PcpCache *cache_)
If supplied, the given PcpCache will be used where possible to compute needed intermediate results.
Definition: primIndex.h:374
PcpPrimIndexInputs & FileFormatTarget(const std::string &target)
The file format target for scene description layers encountered during prim index computation.
Definition: primIndex.h:413
bool IsEquivalentTo(const PcpPrimIndexInputs &params) const
Returns true if prim index computations using this parameters object would be equivalent to computati...
PcpPrimIndexInputs & USD(bool doUSD=true)
Whether the prim stack should be computed, and whether relocates, inherits, permissions,...
Definition: primIndex.h:408
PcpPrimIndexInputs & IncludePayloadPredicate(std::function< bool(const SdfPath &)> predicate)
Optional predicate evaluated when a not-yet-included payload is discovered while indexing.
Definition: primIndex.h:396
PcpPrimIndexInputs & IncludedPayloadsMutex(tbb::spin_rw_mutex *mutex)
Optional mutex for accessing includedPayloads.
Definition: primIndex.h:389
Outputs of the prim indexing procedure.
Definition: primIndex.h:307
PcpExpressionVariablesDependencyData expressionVariablesDependency
Dependencies on expression variables from composition arcs in this prim index.
Definition: primIndex.h:336
PayloadState payloadState
Indicates the payload state of this index.
Definition: primIndex.h:326
PcpErrorVector allErrors
List of all errors encountered during indexing.
Definition: primIndex.h:322
std::vector< PcpCulledDependency > culledDependencies
Site dependencies from nodes in the prim index that have been culled.
Definition: primIndex.h:339
PcpDynamicFileFormatDependencyData dynamicFileFormatDependency
A list of names of fields that were composed to generate dynamic file format arguments for a node in ...
Definition: primIndex.h:332
PcpPrimIndex primIndex
Prim index describing the composition structure for the associated prim.
Definition: primIndex.h:319
PcpNodeRef Append(PcpPrimIndexOutputs &&childOutputs, const PcpArc &arcToParent, PcpErrorBasePtr *error)
Appends the outputs from childOutputs to this object, using arcToParent to connect childOutputs' prim...
PayloadState
Enumerator whose enumerants describe the payload state of this prim index.
Definition: primIndex.h:313
Object used to iterate over prim specs in the prim index graph in strong-to-weak order.
Definition: iterator.h:186
A scene description container that can combine with other such containers to form simple component as...
Definition: layer.h:84
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:274
Represents a prim description in an SdfLayer object.
Definition: primSpec.h:58
Implementation of a hash set using open-addressing and the robin hood hashing algorithm with backward...
Definition: robin_set.h:95
Single-site composition.
Standard pointer typedefs.
#define TF_DECLARE_REF_PTRS(type)
Define standard ref pointer types.
Definition: declarePtrs.h:58
#define TF_DECLARE_WEAK_AND_REF_PTRS(type)
Define standard weak, ref, and vector pointer types.
Definition: declarePtrs.h:72
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:440
std::map< std::string, std::vector< std::string > > PcpVariantFallbackMap
typedef std::map<std::string, std::vector<std::string>> PcpVariantFallbackMap
Definition: types.h:189
std::map< std::string, std::string > SdfVariantSelectionMap
A map of reference variant set names to variants in those sets.
Definition: types.h:258