All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
collectionMembershipQuery.h
Go to the documentation of this file.
1//
2// Copyright 2019 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_USD_COLLECTION_MEMBERSHIP_QUERY_H
8#define PXR_USD_USD_COLLECTION_MEMBERSHIP_QUERY_H
9
11
12#include "pxr/pxr.h"
13
14#include "pxr/usd/usd/common.h"
15#include "pxr/usd/usd/object.h"
17
19#include "pxr/base/tf/hash.h"
21#include "pxr/usd/sdf/path.h"
22#include "pxr/usd/sdf/pathExpression.h"
23#include "pxr/usd/sdf/pathExpressionEval.h"
24
25#include <unordered_map>
26
27PXR_NAMESPACE_OPEN_SCOPE
28
29#define USD_COLLECTION_MEMBERSHIP_QUERY_TOKENS \
30 (IncludedByMembershipExpression) \
31 (ExcludedByMembershipExpression)
32
33TF_DECLARE_PUBLIC_TOKENS(UsdCollectionMembershipQueryTokens,
34 USD_API, USD_COLLECTION_MEMBERSHIP_QUERY_TOKENS);
35
36
37class Usd_CollectionMembershipQueryBase
38{
39public:
49 using PathExpansionRuleMap = std::unordered_map<SdfPath,
50 TfToken, SdfPath::Hash>;
51
54 Usd_CollectionMembershipQueryBase() = default;
55
59 Usd_CollectionMembershipQueryBase(
60 const PathExpansionRuleMap& pathExpansionRuleMap,
61 const SdfPathSet& includedCollections);
62
64 Usd_CollectionMembershipQueryBase(
65 PathExpansionRuleMap&& pathExpansionRuleMap,
66 SdfPathSet&& includedCollections);
67
70 Usd_CollectionMembershipQueryBase(
71 const PathExpansionRuleMap& pathExpansionRuleMap,
72 const SdfPathSet& includedCollections,
73 const TfToken &topExpansionRule);
74
77 Usd_CollectionMembershipQueryBase(
78 PathExpansionRuleMap&& pathExpansionRuleMap,
79 SdfPathSet&& includedCollections,
80 TfToken const &topExpansionRule);
81
85 bool HasExcludes() const {
86 return _hasExcludes;
87 }
88
89
93 const PathExpansionRuleMap& GetAsPathExpansionRuleMap() const {
94 return _pathExpansionRuleMap;
95 }
96
103 const SdfPathSet& GetIncludedCollections() const {
104 return _includedCollections;
105 }
106
112 TfToken GetTopExpansionRule() const {
113 return _topExpansionRule;
114 }
115
116protected:
117
119 struct _Hash {
120 USD_API
121 size_t operator()(Usd_CollectionMembershipQueryBase const& query) const;
122 };
123
125 inline size_t _GetHash() const {
126 return _Hash()(*this);
127 }
128
129 USD_API
130 bool _IsPathIncludedByRuleMap(const SdfPath &path,
131 TfToken *expansionRule=nullptr) const;
132
133 USD_API
134 bool _IsPathIncludedByRuleMap(const SdfPath &path,
135 const TfToken &parentExpansionRule,
136 TfToken *expansionRule=nullptr) const;
137
138 // Return true if the _pathExpansionRuleMap is empty, meaning that we would
139 // use an expression in the derived class, for example.
140 USD_API
141 bool _HasEmptyRuleMap() const;
142
143 TfToken _topExpansionRule;
144
145 PathExpansionRuleMap _pathExpansionRuleMap;
146
147 SdfPathSet _includedCollections;
148
149 // A cached flag indicating whether _pathExpansionRuleMap contains
150 // any exclude rules.
151 bool _hasExcludes=false;
152};
153
157USD_API
160 Usd_CollectionMembershipQueryBase::PathExpansionRuleMap const &ruleMap);
161
162// -------------------------------------------------------------------------- //
163// UsdCollectionMembershipQuery //
164// -------------------------------------------------------------------------- //
172template <class ExprEval>
173class Usd_CollectionMembershipQuery : public Usd_CollectionMembershipQueryBase
174{
175public:
176 using ExpressionEvaluator = ExprEval;
177
178 using Usd_CollectionMembershipQueryBase::Usd_CollectionMembershipQueryBase;
179
208 IsPathIncluded(const SdfPath &path,
209 TfToken *expansionRule=nullptr) const {
210 // If we have a rule map, go that way. Otherwise try the expression.
211 if (UsesPathExpansionRuleMap()) {
213 _IsPathIncludedByRuleMap(path, expansionRule));
214 }
216 res = GetExpressionEvaluator().Match(path);
217 if (expansionRule) {
218 *expansionRule = res ?
219 UsdCollectionMembershipQueryTokens->
220 IncludedByMembershipExpression :
221 UsdCollectionMembershipQueryTokens->
222 ExcludedByMembershipExpression;
223 }
224 return res;
225 }
226
246 IsPathIncluded(const SdfPath &path,
247 const TfToken &parentExpansionRule,
248 TfToken *expansionRule=nullptr) const {
249 // If we have a rule map, go that way. Otherwise try the expression.
250 if (UsesPathExpansionRuleMap()) {
252 _IsPathIncludedByRuleMap(
253 path, parentExpansionRule, expansionRule));
254 }
256 res = GetExpressionEvaluator().Match(path);
257 if (expansionRule) {
258 *expansionRule = res ?
259 UsdCollectionMembershipQueryTokens->
260 IncludedByMembershipExpression :
261 UsdCollectionMembershipQueryTokens->
262 ExcludedByMembershipExpression;
263 }
264 return res;
265 }
266
270 bool UsesPathExpansionRuleMap() const {
271 return !_HasEmptyRuleMap();
272 }
273
274 void
275 SetExpressionEvaluator(ExpressionEvaluator &&exprEval) {
276 _exprEval = std::move(exprEval);
277 }
278
279 void
280 SetExpressionEvaluator(ExpressionEvaluator const &exprEval) {
281 SetExpressionEvaluator(ExpressionEvaluator { exprEval } );
282 }
283
286 ExpressionEvaluator const &
287 GetExpressionEvaluator() const {
288 return _exprEval;
289 }
290
293 bool HasExpression() const {
294 return !_exprEval.IsEmpty();
295 }
296
298 bool operator==(Usd_CollectionMembershipQuery const& rhs) const {
299 // Note that MembershipQuery objects that have non-empty _exprEval never
300 // compare equal to each other. This is because the evaluator objects
301 // run code, and there's no good way to determine equivalence.
302 return _topExpansionRule == rhs._topExpansionRule &&
303 _hasExcludes == rhs._hasExcludes &&
304 _pathExpansionRuleMap == rhs._pathExpansionRuleMap &&
305 _includedCollections == rhs._includedCollections &&
306 _exprEval.IsEmpty() == rhs._exprEval.IsEmpty();
307 ;
308 }
309
311 bool operator!=(Usd_CollectionMembershipQuery const& rhs) const {
312 return !(*this == rhs);
313 }
314
316 struct Hash {
317 size_t operator()(Usd_CollectionMembershipQuery const& query) const {
318 return TfHash::Combine(query._GetHash(), query._exprEval.IsEmpty());
319 }
320 };
321
323 inline size_t GetHash() const {
324 return Hash()(*this);
325 }
326
327private:
328 ExpressionEvaluator _exprEval;
329};
330
331
336 struct PathToObj {
337 UsdObject operator()(SdfPath const &path) const {
338 return stage->GetObjectAtPath(path);
339 }
340 UsdStageWeakPtr stage;
341 };
342
343public:
345 using IncrementalSearcher =
346 typename PathExprEval::IncrementalSearcher<PathToObj>;
347
350
361 USD_API
362 UsdObjectCollectionExpressionEvaluator(UsdStageWeakPtr const &stage,
363 SdfPathExpression const &expr);
364
367 bool IsEmpty() const {
368 return !_stage || _evaluator.IsEmpty();
369 }
370
373 UsdStageWeakPtr const &GetStage() const { return _stage; }
374
376 USD_API
378 Match(SdfPath const &path) const;
379
381 USD_API
383 Match(UsdObject const &object) const;
384
392 USD_API
393 IncrementalSearcher MakeIncrementalSearcher() const;
394
395private:
396 UsdStageWeakPtr _stage;
397 PathExprEval _evaluator;
398};
399
401 Usd_CollectionMembershipQuery<UsdObjectCollectionExpressionEvaluator>;
402
408USD_API
410 const UsdCollectionMembershipQuery &query,
411 const UsdStageWeakPtr &stage,
412 const Usd_PrimFlagsPredicate &pred=UsdPrimDefaultPredicate);
413
419USD_API
421 const UsdCollectionMembershipQuery &query,
422 const UsdStageWeakPtr &stage,
423 const Usd_PrimFlagsPredicate &pred=UsdPrimDefaultPredicate);
424
425PXR_NAMESPACE_CLOSE_SCOPE
426
427#endif
Objects of this class represent a logical expression syntax tree consisting of SdfPathPattern s,...
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:274
Represents the result of a predicate function: a pair of the boolean result and a Constancy token ind...
static SdfPredicateFunctionResult MakeVarying(bool value)
Create with value and 'MayVaryOverDescendants'.
static size_t Combine(Args &&... args)
Produce a hash code by combining the hash codes of several objects.
Definition: hash.h:475
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:71
Represents a flattened view of a collection.
Evaluates SdfPathExpressions with objects from a given UsdStage.
USD_API IncrementalSearcher MakeIncrementalSearcher() const
Create an incremental searcher from this evaluator.
UsdObjectCollectionExpressionEvaluator()=default
Construct an empty evaluator.
USD_API SdfPredicateFunctionResult Match(UsdObject const &object) const
Return the result of evaluating the expression against object.
bool IsEmpty() const
Return true if this evaluator has an invalid stage or an empty underlying SdfPathExpressionEval objec...
UsdStageWeakPtr const & GetStage() const
Return the stage this object was constructed with, or nullptr if it was default constructed.
USD_API SdfPredicateFunctionResult Match(SdfPath const &path) const
Return the result of evaluating the expression against path.
USD_API UsdObjectCollectionExpressionEvaluator(UsdStageWeakPtr const &stage, SdfPathExpression const &expr)
Construct an evaluator that evalutates expr on objects from stage.
Base class for Usd scenegraph objects, providing common API.
Definition: object.h:115
USD_API std::set< UsdObject > UsdComputeIncludedObjectsFromCollection(const UsdCollectionMembershipQuery &query, const UsdStageWeakPtr &stage, const Usd_PrimFlagsPredicate &pred=UsdPrimDefaultPredicate)
Returns all the usd objects that satisfy the predicate, pred in the collection represented by the Usd...
USD_API SdfPathSet UsdComputeIncludedPathsFromCollection(const UsdCollectionMembershipQuery &query, const UsdStageWeakPtr &stage, const Usd_PrimFlagsPredicate &pred=UsdPrimDefaultPredicate)
Returns all the paths that satisfy the predicate, pred in the collection represented by the UsdCollec...
USD_API SdfPathExpression UsdComputePathExpressionFromCollectionMembershipQueryRuleMap(Usd_CollectionMembershipQueryBase::PathExpansionRuleMap const &ruleMap)
Compute an SdfPathExpression that matches the same paths as ruleMap.
Standard pointer typedefs.
unspecified UsdPrimDefaultPredicate
The default predicate used for prim traversals in methods like UsdPrim::GetChildren,...
This file defines some macros that are useful for declaring and using static TfTokens.
#define TF_DECLARE_PUBLIC_TOKENS(...)
Macro to define public tokens.
Definition: staticTokens.h:81