HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
collectionAPI.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 USD_GENERATED_COLLECTIONAPI_H
8 #define USD_GENERATED_COLLECTIONAPI_H
9 
10 /// \file usd/collectionAPI.h
11 
12 #include "pxr/pxr.h"
13 #include "pxr/usd/usd/api.h"
15 #include "pxr/usd/usd/prim.h"
16 #include "pxr/usd/usd/stage.h"
17 #include "pxr/usd/usd/tokens.h"
18 
20 #include "pxr/usd/usd/primFlags.h"
21 #include "pxr/usd/usd/tokens.h"
23 
24 
25 #include "pxr/base/vt/value.h"
26 
27 #include "pxr/base/gf/vec3d.h"
28 #include "pxr/base/gf/vec3f.h"
29 #include "pxr/base/gf/matrix4d.h"
30 
31 #include "pxr/base/tf/token.h"
32 #include "pxr/base/tf/type.h"
33 
35 
36 class SdfAssetPath;
37 
38 // -------------------------------------------------------------------------- //
39 // COLLECTIONAPI //
40 // -------------------------------------------------------------------------- //
41 
42 /// \class UsdCollectionAPI
43 ///
44 /// A general purpose API schema used to describe a collection of prims
45 /// and properties within a scene. This API schema can be applied to a prim
46 /// multiple times with different instance names to define several collections
47 /// on a single prim.
48 ///
49 /// A collection's membership is specified one of two ways. The first way uses
50 /// the built-in relationships `includes` and `excludes`, and the attribute
51 /// `includeRoot` to determine membership. The second way is termed a
52 /// pattern-based collection, and uses the built-in attribute
53 /// `membershipExpression` to determine membership. Here we will refer to
54 /// collections using `includes`, `excludes` and `includeRoot` as being in
55 /// *relationship-mode* and those using the `membershipExpression` as being in
56 /// *expression-mode*.
57 ///
58 /// A collection is determined to be in *relationship-mode* when either or both
59 /// of its `includes` and `excludes` relationships have valid targets, or the
60 /// `includeRoot` attribute is set `true`. In this case, the pattern-based
61 /// `membershipExpression` attribute is ignored. Otherwise, the collection is
62 /// in *expression-mode* and the `membershipExpression` attribute applies.
63 ///
64 /// In *relationship-mode* the `includes` and `excludes` relationships specify
65 /// the collection members as a set of paths to include and a set of paths to
66 /// exclude. Whether or not the descendants of an included path belong to a
67 /// collection is decided by its expansion rule (see below). If the collection
68 /// excludes paths that are not descendent to included paths, the collection
69 /// implicitly includes the root path `</>`. If such a collection also
70 /// includes paths that are not descendent to the excluded paths, it is
71 /// considered invalid since the intent is ambiguous.
72 ///
73 /// In *expression-mode*, the pattern-based `membershipExpression` attribute is
74 /// used with the `expansionRule` attribute to determine collection membership.
75 /// See the detailed descriptions of the built-in properties below for more
76 /// details.
77 ///
78 /// \section usd_collectionapi_properties Collection API Properties
79 ///
80 /// The built-in properties for this schema are in the `collection:instanceName`
81 /// namespace, where `instanceName` is the user-provided applied API schema
82 /// instance name.
83 ///
84 /// <ul>
85 /// <li>`uniform token collection:instanceName:expansionRule` - in
86 /// *relationship-mode*, specifies how to expand the `includes` and `excludes`
87 /// relationship targets to determine the collection's members. In
88 /// *expression-mode*, specifies how matching scene objects against the
89 /// `membershipExpression` proceeds. Possible values include:
90 /// <ul>
91 /// <li>`expandPrims` - in *relationship-mode*, all the prims descendent
92 /// to the `includes` relationship targets (and not descendent to `excludes`
93 /// relationship targets) belong to the collection. Any `includes`-targeted
94 /// property paths also belong to the collection. This is the default
95 /// behavior. In *expression-mode*, the functions
96 /// UsdComputeIncludedObjectsFromCollection() and
97 /// UsdComputeIncludedPathsFromCollection() only test prims against the
98 /// `membershipExpression` to determine membership.
99 /// </li>
100 /// <li>`expandPrimsAndProperties` - like `expandPrims`, but in
101 /// *relationship-mode*, all properties on all included prims also belong to
102 /// the collection. In *expression-mode*, the functions
103 /// UsdComputeIncludedObjectsFromCollection() and
104 /// UsdComputeIncludedPathsFromCollection() test both prims and
105 /// properties against the `membershipExpression` to determine membership.
106 /// </li>
107 /// <li>`explicitOnly` - in *relationship-mode*, only paths in the
108 /// `includes` relationship targets and not those in the `excludes`
109 /// relationship targets belong to the collection. Does not apply to
110 /// *expression-mode*. If set in *expression-mode*, the functions
111 /// UsdComputeIncludedObjectsFromCollection() and
112 /// UsdComputeIncludedPathsFromCollection() return no results.
113 /// </li>
114 /// </ul>
115 /// </li>
116 ///
117 /// <li>`bool collection:instanceName:includeRoot` - boolean attribute
118 /// indicating whether the pseudo-root path `</>` should be counted as one
119 /// of the included target paths in *relationship-mode*. This separate attribute
120 /// is required because relationships cannot directly target the root. When
121 /// `expansionRule` is `explicitOnly`, this attribute is ignored. The fallback
122 /// value is false. When set to `true`, this collection is in
123 /// *relationship-mode*. This attribute is ignored in *expression-mode*. </li>
124 ///
125 /// <li>`rel collection:instanceName:includes` - in *relationship-mode*,
126 /// specifies a list of targets that are included in the collection. This can
127 /// target prims or properties directly. A collection can insert the rules of
128 /// another collection by making its `includes` relationship target the
129 /// `collection:otherInstanceName` property from the collection to be included
130 /// (see UsdCollectionAPI::GetCollectionAttr). Note that including another
131 /// collection does not guarantee the contents of that collection will be in the
132 /// final collection; instead, the rules are merged. This means, for example,
133 /// an exclude entry may exclude a portion of the included collection. When a
134 /// collection includes one or more collections, the order in which targets are
135 /// added to the includes relationship may become significant, if there are
136 /// conflicting opinions about the same path. Targets that are added later are
137 /// considered to be stronger than earlier targets for the same path. This
138 /// relationship is ignored in *expression-mode*.</li>
139 ///
140 /// <li>`rel collection:instanceName:excludes` - in *relationship-mode*,
141 /// specifies a list of targets that are excluded below the <b>included</b>
142 /// paths in this collection. This can target prims or properties directly, but
143 /// <b>cannot target another collection</b>. This is to keep the membership
144 /// determining logic simple, efficient and easier to reason about. Finally, it
145 /// is invalid for a collection to exclude paths that are not included in
146 /// it. The presence of such "orphaned" excluded paths will not affect the set
147 /// of paths included in the collection, but may affect the performance of
148 /// querying membership of a path in the collection (see
149 /// UsdCollectionMembershipQuery::IsPathIncluded) or of enumerating the
150 /// objects belonging to the collection (see
151 /// UsdCollectionAPI::ComputeIncludedObjects). This relationship is ignored in
152 /// *expression-mode*.</li>
153 ///
154 /// <li>`uniform opaque collection:instanceName` - opaque
155 /// attribute (meaning it can never have a value) that represents the collection
156 /// for the purpose of allowing another collection to include it in
157 /// *relationship-mode*. When this property is targeted by another collection's
158 /// `includes` relationship, the rules of this collection will be inserted
159 /// into the rules of the collection that includes it.</li>
160 ///
161 /// <li>`uniform pathExpression collection:instanceName:membershipExpression` -
162 /// in *expression-mode*, defines the SdfPathExpression used to test
163 /// objects for collection membership.</li>
164 ///
165 /// </ul>
166 ///
167 /// \subsection usd_collectionapi_implicit_inclusion Implicit Inclusion
168 ///
169 /// In some scenarios it is useful to express a collection that includes
170 /// everything except certain paths. To support this, a *relationship-mode*
171 /// collection that has an exclude that is not descendent to any include will
172 /// include the root path `</>`.
173 ///
174 /// \section usd_collectionapi_creating_cpp Creating Collections in C++
175 ///
176 /// \snippet examples_usd.cpp ApplyCollections
177 ///
178 ///
179 /// For any described attribute \em Fallback \em Value or \em Allowed \em Values below
180 /// that are text/tokens, the actual token is published and defined in \ref UsdTokens.
181 /// So to set an attribute to the value "rightHanded", use UsdTokens->rightHanded
182 /// as the value.
183 ///
185 {
186 public:
187  /// Compile time constant representing what kind of schema this class is.
188  ///
189  /// \sa UsdSchemaKind
191 
192  /// Construct a UsdCollectionAPI on UsdPrim \p prim with
193  /// name \p name . Equivalent to
194  /// UsdCollectionAPI::Get(
195  /// prim.GetStage(),
196  /// prim.GetPath().AppendProperty(
197  /// "collection:name"));
198  ///
199  /// for a \em valid \p prim, but will not immediately throw an error for
200  /// an invalid \p prim
202  const UsdPrim& prim=UsdPrim(), const TfToken &name=TfToken())
203  : UsdAPISchemaBase(prim, /*instanceName*/ name)
204  { }
205 
206  /// Construct a UsdCollectionAPI on the prim held by \p schemaObj with
207  /// name \p name. Should be preferred over
208  /// UsdCollectionAPI(schemaObj.GetPrim(), name), as it preserves
209  /// SchemaBase state.
211  const UsdSchemaBase& schemaObj, const TfToken &name)
212  : UsdAPISchemaBase(schemaObj, /*instanceName*/ name)
213  { }
214 
215  /// Destructor.
216  USD_API
217  virtual ~UsdCollectionAPI();
218 
219  /// Return a vector of names of all pre-declared attributes for this schema
220  /// class and all its ancestor classes. Does not include attributes that
221  /// may be authored by custom/extended methods of the schemas involved.
222  USD_API
223  static const TfTokenVector &
224  GetSchemaAttributeNames(bool includeInherited=true);
225 
226  /// Return a vector of names of all pre-declared attributes for this schema
227  /// class and all its ancestor classes for a given instance name. Does not
228  /// include attributes that may be authored by custom/extended methods of
229  /// the schemas involved. The names returned will have the proper namespace
230  /// prefix.
231  USD_API
232  static TfTokenVector
233  GetSchemaAttributeNames(bool includeInherited, const TfToken &instanceName);
234 
235  /// Returns the name of this multiple-apply schema instance
236  TfToken GetName() const {
237  return _GetInstanceName();
238  }
239 
240  /// Return a UsdCollectionAPI holding the prim adhering to this
241  /// schema at \p path on \p stage. If no prim exists at \p path on
242  /// \p stage, or if the prim at that path does not adhere to this schema,
243  /// return an invalid schema object. \p path must be of the format
244  /// <path>.collection:name .
245  ///
246  /// This is shorthand for the following:
247  ///
248  /// \code
249  /// TfToken name = SdfPath::StripNamespace(path.GetToken());
250  /// UsdCollectionAPI(
251  /// stage->GetPrimAtPath(path.GetPrimPath()), name);
252  /// \endcode
253  ///
254  USD_API
255  static UsdCollectionAPI
256  Get(const UsdStagePtr &stage, const SdfPath &path);
257 
258  /// Return a UsdCollectionAPI with name \p name holding the
259  /// prim \p prim. Shorthand for UsdCollectionAPI(prim, name);
260  USD_API
261  static UsdCollectionAPI
262  Get(const UsdPrim &prim, const TfToken &name);
263 
264  /// Return a vector of all named instances of UsdCollectionAPI on the
265  /// given \p prim.
266  USD_API
267  static std::vector<UsdCollectionAPI>
268  GetAll(const UsdPrim &prim);
269 
270  /// Checks if the given name \p baseName is the base name of a property
271  /// of CollectionAPI.
272  USD_API
273  static bool
274  IsSchemaPropertyBaseName(const TfToken &baseName);
275 
276  /// Checks if the given path \p path is of an API schema of type
277  /// CollectionAPI. If so, it stores the instance name of
278  /// the schema in \p name and returns true. Otherwise, it returns false.
279  USD_API
280  static bool
282 
283  /// Returns true if this <b>multiple-apply</b> API schema can be applied,
284  /// with the given instance name, \p name, to the given \p prim. If this
285  /// schema can not be a applied the prim, this returns false and, if
286  /// provided, populates \p whyNot with the reason it can not be applied.
287  ///
288  /// Note that if CanApply returns false, that does not necessarily imply
289  /// that calling Apply will fail. Callers are expected to call CanApply
290  /// before calling Apply if they want to ensure that it is valid to
291  /// apply a schema.
292  ///
293  /// \sa UsdPrim::GetAppliedSchemas()
294  /// \sa UsdPrim::HasAPI()
295  /// \sa UsdPrim::CanApplyAPI()
296  /// \sa UsdPrim::ApplyAPI()
297  /// \sa UsdPrim::RemoveAPI()
298  ///
299  USD_API
300  static bool
301  CanApply(const UsdPrim &prim, const TfToken &name,
302  std::string *whyNot=nullptr);
303 
304  /// Applies this <b>multiple-apply</b> API schema to the given \p prim
305  /// along with the given instance name, \p name.
306  ///
307  /// This information is stored by adding "CollectionAPI:<i>name</i>"
308  /// to the token-valued, listOp metadata \em apiSchemas on the prim.
309  /// For example, if \p name is 'instance1', the token
310  /// 'CollectionAPI:instance1' is added to 'apiSchemas'.
311  ///
312  /// \return A valid UsdCollectionAPI object is returned upon success.
313  /// An invalid (or empty) UsdCollectionAPI object is returned upon
314  /// failure. See \ref UsdPrim::ApplyAPI() for
315  /// conditions resulting in failure.
316  ///
317  /// \sa UsdPrim::GetAppliedSchemas()
318  /// \sa UsdPrim::HasAPI()
319  /// \sa UsdPrim::CanApplyAPI()
320  /// \sa UsdPrim::ApplyAPI()
321  /// \sa UsdPrim::RemoveAPI()
322  ///
323  USD_API
324  static UsdCollectionAPI
325  Apply(const UsdPrim &prim, const TfToken &name);
326 
327 protected:
328  /// Returns the kind of schema this class belongs to.
329  ///
330  /// \sa UsdSchemaKind
331  USD_API
332  UsdSchemaKind _GetSchemaKind() const override;
333 
334 private:
335  // needs to invoke _GetStaticTfType.
336  friend class UsdSchemaRegistry;
337  USD_API
338  static const TfType &_GetStaticTfType();
339 
340  static bool _IsTypedSchema();
341 
342  // override SchemaBase virtuals.
343  USD_API
344  const TfType &_GetTfType() const override;
345 
346 public:
347  // --------------------------------------------------------------------- //
348  // EXPANSIONRULE
349  // --------------------------------------------------------------------- //
350  /// Specifies how the paths that are included in
351  /// the collection must be expanded to determine its members.
352  ///
353  /// | ||
354  /// | -- | -- |
355  /// | Declaration | `uniform token expansionRule = "expandPrims"` |
356  /// | C++ Type | TfToken |
357  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
358  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
359  /// | \ref UsdTokens "Allowed Values" | explicitOnly, expandPrims, expandPrimsAndProperties |
360  USD_API
362 
363  /// See GetExpansionRuleAttr(), and also
364  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
365  /// If specified, author \p defaultValue as the attribute's default,
366  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
367  /// the default for \p writeSparsely is \c false.
368  USD_API
369  UsdAttribute CreateExpansionRuleAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
370 
371 public:
372  // --------------------------------------------------------------------- //
373  // INCLUDEROOT
374  // --------------------------------------------------------------------- //
375  /// Boolean attribute indicating whether the pseudo-root
376  /// path `</>` should be counted as one of the included target
377  /// paths. The fallback is false. This separate attribute is
378  /// required because relationships cannot directly target the root.
379  ///
380  /// | ||
381  /// | -- | -- |
382  /// | Declaration | `uniform bool includeRoot` |
383  /// | C++ Type | bool |
384  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Bool |
385  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
386  USD_API
388 
389  /// See GetIncludeRootAttr(), and also
390  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
391  /// If specified, author \p defaultValue as the attribute's default,
392  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
393  /// the default for \p writeSparsely is \c false.
394  USD_API
395  UsdAttribute CreateIncludeRootAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
396 
397 public:
398  // --------------------------------------------------------------------- //
399  // MEMBERSHIPEXPRESSION
400  // --------------------------------------------------------------------- //
401  /// Specifies a path expression that determines membership in this
402  /// collection.
403  ///
404  /// | ||
405  /// | -- | -- |
406  /// | Declaration | `uniform pathExpression membershipExpression` |
407  /// | C++ Type | SdfPathExpression |
408  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->PathExpression |
409  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
410  USD_API
412 
413  /// See GetMembershipExpressionAttr(), and also
414  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
415  /// If specified, author \p defaultValue as the attribute's default,
416  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
417  /// the default for \p writeSparsely is \c false.
418  USD_API
419  UsdAttribute CreateMembershipExpressionAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
420 
421 public:
422  // --------------------------------------------------------------------- //
423  // COLLECTION
424  // --------------------------------------------------------------------- //
425  /// This property represents the collection for the purpose of
426  /// allowing another collection to include it. When this property is
427  /// targeted by another collection's <i>includes</i> relationship, the rules
428  /// of this collection will be inserted into the rules of the collection
429  /// that includes it.
430  ///
431  ///
432  /// | ||
433  /// | -- | -- |
434  /// | Declaration | `uniform opaque __INSTANCE_NAME__` |
435  /// | C++ Type | SdfOpaqueValue |
436  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Opaque |
437  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
438  USD_API
440 
441  /// See GetCollectionAttr(), and also
442  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
443  /// If specified, author \p defaultValue as the attribute's default,
444  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
445  /// the default for \p writeSparsely is \c false.
446  USD_API
447  UsdAttribute CreateCollectionAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
448 
449 public:
450  // --------------------------------------------------------------------- //
451  // INCLUDES
452  // --------------------------------------------------------------------- //
453  /// Specifies a list of targets that are included in the collection.
454  /// This can target prims or properties directly. A collection can insert
455  /// the rules of another collection by making its <i>includes</i>
456  /// relationship target the <b>collection:{collectionName}</b> property on
457  /// the owning prim of the collection to be included
458  ///
459  USD_API
461 
462  /// See GetIncludesRel(), and also
463  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create
464  USD_API
466 
467 public:
468  // --------------------------------------------------------------------- //
469  // EXCLUDES
470  // --------------------------------------------------------------------- //
471  /// Specifies a list of targets that are excluded below
472  /// the included paths in this collection. This can target prims or
473  /// properties directly, but cannot target another collection. This is to
474  /// keep the membership determining logic simple, efficient and easier to
475  /// reason about. Finally, it is invalid for a collection to exclude
476  /// paths that are not included in it. The presence of such "orphaned"
477  /// excluded paths will not affect the set of paths included in the
478  /// collection, but may affect the performance of querying membership of
479  /// a path in the collection (see
480  /// UsdCollectionAPI::MembershipQuery::IsPathIncluded)
481  /// or of enumerating the objects belonging to the collection (see
482  /// UsdCollectionAPI::GetIncludedObjects).
483  ///
484  USD_API
486 
487  /// See GetExcludesRel(), and also
488  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create
489  USD_API
491 
492 public:
493  // ===================================================================== //
494  // Feel free to add custom code below this line, it will be preserved by
495  // the code generator.
496  //
497  // Just remember to:
498  // - Close the class declaration with };
499  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
500  // - Close the include guard with #endif
501  // ===================================================================== //
502  // --(BEGIN CUSTOM CODE)--
503 
504 public:
505  /// Returns the collection represented by the given collection path,
506  /// \p collectionPath on the given USD stage.
507  USD_API
508  static UsdCollectionAPI GetCollection(const UsdStagePtr &stage,
509  const SdfPath &collectionPath);
510 
511  /// Returns the schema object representing a collection named \p name on
512  /// the given \p prim.
513  USD_API
514  static UsdCollectionAPI GetCollection(const UsdPrim &prim,
515  const TfToken &name);
516 
517  /// Returns all the named collections on the given USD prim.
518  /// \deprecated Use GetAll(prim) instead.
519  USD_API
520  static std::vector<UsdCollectionAPI> GetAllCollections(const UsdPrim &prim);
521 
522  /// Returns the canonical path that represents this collection.
523  /// This points to the property named "collection:{collectionName}" on the
524  /// prim defining the collection. This is the path to be used to "include"
525  /// this collection in another collection.
526  ///
527  /// \sa GetCollectionAttr()
528  USD_API
529  SdfPath GetCollectionPath() const;
530 
531  /// Returns the canonical path to the collection named, \p name on the given
532  /// prim, \p prim.
533  ///
534  /// \sa GetCollectionPath()
535  USD_API
537  const UsdPrim &prim,
538  const TfToken &collectionName);
539 
540  /// Obtain a complete SdfPathExpression from this collection's
541  /// membershipExpression. First, UsdAttribute::Get() the value of
542  /// GetMembershipExpressionAttr(), then resolve any contained references.
543  /// Replace any remaining "weaker" references (%_) with
544  /// SdfPathExpression::Nothing(). Replace other references by recursively
545  /// resolving the expressions from the collections on the referenced prims.
546  /// If no such prims or no such collections exist, replace those references
547  /// with SdfPathExpression::Nothing() as well.
548  USD_API
550 
551  // Convenient alias for UsdCollectionMembershipQuery object
553 
554  /// Computes and returns a UsdCollectionMembershipQuery object which can
555  /// be used to query inclusion or exclusion of paths in the collection.
556  USD_API
558 
559  /// Populates the UsdCollectionMembershipQuery object with data from this
560  /// collection, so it can be used to query inclusion or exclusion of paths.
561  USD_API
563 
564  /// Return true if the collection cannot possibly include anything.
565  ///
566  /// For collections in relationships-mode, this is the case if the includes
567  /// relationship has no target paths, and the includeRoot attribute is
568  /// false.
569  ///
570  /// For collections in expression-mode, this is the case if the
571  /// membershipExpression attribute has either no opinion or if it is
572  /// SdfPathExpression::Nothing().
573  ///
574  /// Note that there may be cases where the collection includes no objects
575  /// despite HasNoIncludedPaths() returning false. For example, if the
576  /// included objects are unloaded, or if the included objects are also
577  /// excluded, or if an authored non-empty membershipExpression happens not
578  /// to match any objects on the stage.
579  USD_API
580  bool HasNoIncludedPaths() const;
581 
582  /// Return true if this collection is *relationships-mode*. That is, if it
583  /// uses the `includes` and `excludes` relationships to determine membership
584  /// and not the `membershipExpression` attribute. This is the case when
585  /// either or both of its `includes` and `excludes` relationships have valid
586  /// targets, or the `includeRoot` attribute is set `true`. This is
587  /// equivalent to `!IsInExpressionMode()`.
588  USD_API
589  bool IsInRelationshipsMode() const;
590 
591  /// Return true if this collection is *expression-mode*. That is, if it
592  /// uses the `membershipExpression` attribute to determine membership and
593  /// not the `includes` and `excludes` relationships. Equivalent to
594  /// `!IsInRelationshipsMode()`.
595  bool IsInExpressionMode() const {
596  return !IsInRelationshipsMode();
597  }
598 
599  /// Returns all the usd objects that satisfy the predicate, \p pred in the
600  /// collection represented by the UsdCollectionMembershipQuery object, \p
601  /// query.
602  ///
603  /// The results depends on the load state of the UsdStage, \p stage.
604  USD_API
605  static std::set<UsdObject> ComputeIncludedObjects(
607  const UsdStageWeakPtr &stage,
609 
610  /// Returns all the paths that satisfy the predicate, \p pred in the
611  /// collection represented by the UsdCollectionMembershipQuery object, \p
612  /// query.
613  ///
614  /// The result depends on the load state of the UsdStage, \p stage.
615  USD_API
618  const UsdStageWeakPtr &stage,
620 
621  /// \anchor UsdCollectionAPI_AuthoringAPI
622  /// \name Collection Authoring API
623  ///
624  /// Convenience API for adding or removing prims and properties to (or
625  /// from) a collection..
626  ///
627  /// @{
628 
629  /// Includes or adds the given path, \p pathToInclude in the collection.
630  ///
631  /// This does nothing if the path is already included in the collection.
632  ///
633  /// This does not modify the expansion-rule of the collection. Hence, if the
634  /// expansionRule is <i>expandPrims</i> or <i>expandPrimsAndProperties</i>,
635  /// then the descendants of \p pathToInclude will be also included in the
636  /// collection unless explicitly excluded.
637  ///
638  /// \sa UsdCollectionAPI::ExcludePath()
639  USD_API
640  bool IncludePath(const SdfPath &pathToInclude) const;
641 
642  /// Excludes or removes the given path, \p pathToExclude from the collection.
643  ///
644  /// If the collection is empty, the collection becomes one that
645  /// includes all paths except the givne path. Otherwise, this does
646  /// nothing if the path is not included in the collection.
647  ///
648  /// This does not modify the expansion-rule of the collection. Hence, if the
649  /// expansionRule is <i>expandPrims</i> or <i>expandPrimsAndProperties</i>,
650  /// then the descendants of \p pathToExclude will also be excluded from the
651  /// collection, unless explicitly included.
652  ///
653  /// \sa UsdCollectionAPI::IncludePath()
654  USD_API
655  bool ExcludePath(const SdfPath &pathToExclude) const;
656 
657  /// @}
658 
659  /// Validates the collection by checking the following rules:
660  /// * a collection's expansionRule should be one of "explicitOnly",
661  /// "expandPrims" or "expandPrimsAndProperties".
662  /// * a collection should not have have a circular dependency on
663  /// another collection.
664  /// * a collection should not have both includes and excludes
665  /// among its top-level rules
666  USD_API
667  bool Validate(std::string *reason) const;
668 
669  /// Resets the collection by clearing both the includes and excludes
670  /// targets of the collection in the current UsdEditTarget.
671  ///
672  /// \note This does not modify the "includeRoot" attribute which is used
673  /// to include or exclude everything (i.e. the pseudoRoot) in the USD stage.
674  USD_API
675  bool ResetCollection() const;
676 
677  /// Blocks the targets of the includes and excludes relationships of the
678  /// collection, making it
679  /// <* <i>empty</i> if "includeRoot" is false (or unset) or
680  /// * <i>include everything</i> if "includeRoot" is true.
681  /// (assuming there are no opinions in stronger edit targets).
682  USD_API
683  bool BlockCollection() const;
684 
685  /// Test whether a given \p name contains the "collection:" prefix
686  ///
687  USD_API
688  static bool CanContainPropertyName(const TfToken &name);
689 
690 private:
691 
692  // Helper method for computing the UsdCollectionMembershipQuery object for
693  // a collection.
694  // This makes recursive calls if the collection includes other collections.
695  // \p chainedCollectionPaths is used to pass in the set of all seen and
696  // included collections in the dependency chain and is used to detect
697  // circular dependencies.
698  // If \p foundCircularDependency is not nullptr, it is set to true if a
699  // circular dependency is detected amongst the included collections.
700  // If it is nullptr, a warning is issued when a circular dependency is
701  // detected.
702  void _ComputeMembershipQueryImpl(
704  const SdfPathSet &chainedCollectionPaths,
705  bool *foundCircularDependency=nullptr) const;
706 
707  // The same as ResolveCompleteMembershipExpression(), but set
708  // `foundCircularDependency` to true if a circular dependency is encountered
709  // during resolution.
711  _ResolveCompleteMembershipExpression(bool *foundCircularDependency) const;
712 };
713 
715 
716 #endif
static USD_API UsdCollectionAPI Apply(const UsdPrim &prim, const TfToken &name)
USD_API UsdCollectionMembershipQuery ComputeMembershipQuery() const
GLenum query
Definition: glad.h:2772
USD_API bool BlockCollection() const
static USD_API SdfPath GetNamedCollectionPath(const UsdPrim &prim, const TfToken &collectionName)
static USD_API std::vector< UsdCollectionAPI > GetAllCollections(const UsdPrim &prim)
#define USD_API
Definition: api.h:23
USD_API UsdRelationship GetExcludesRel() const
USD_API bool HasNoIncludedPaths() const
USD_API UsdAttribute GetIncludeRootAttr() const
USD_API bool IncludePath(const SdfPath &pathToInclude) const
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
USD_API UsdRelationship CreateExcludesRel() const
Represents a flattened view of a collection. For more information about collections, please see UsdCollectionAPI as a way to encode and retrieve a collection from scene description. A UsdCollectionMembershipQuery object can be used to answer queries about membership of paths in the collection efficiently.
static USD_API bool CanApply(const UsdPrim &prim, const TfToken &name, std::string *whyNot=nullptr)
UsdStagePtr UsdStageWeakPtr
Definition: common.h:38
USD_API bool ResetCollection() const
USD_API SdfPathExpression ResolveCompleteMembershipExpression() const
USD_API UsdRelationship CreateIncludesRel() const
static USD_API UsdCollectionAPI Get(const UsdStagePtr &stage, const SdfPath &path)
USD_API UsdAttribute CreateExpansionRuleAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
const TfToken & _GetInstanceName() const
TfToken GetName() const
Returns the name of this multiple-apply schema instance.
Definition: token.h:70
static USD_API bool IsCollectionAPIPath(const SdfPath &path, TfToken *name)
USD_API SdfPath GetCollectionPath() const
static USD_API UsdCollectionAPI GetCollection(const UsdStagePtr &stage, const SdfPath &collectionPath)
USD_API UsdAttribute CreateMembershipExpressionAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USD_API bool Validate(std::string *reason) const
USD_API UsdAttribute GetMembershipExpressionAttr() const
USD_API UsdAttribute GetExpansionRuleAttr() const
Definition: prim.h:116
static USD_API bool IsSchemaPropertyBaseName(const TfToken &baseName)
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:440
GLuint const GLchar * name
Definition: glcorearb.h:786
Definition: path.h:273
USD_API UsdAttribute GetCollectionAttr() const
std::set< class SdfPath > SdfPathSet
A set of SdfPaths.
Definition: path.h:192
UsdSchemaKind
Definition: common.h:112
USD_API UsdAttribute CreateCollectionAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USD_API const Usd_PrimFlagsConjunction UsdPrimDefaultPredicate
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
static const UsdSchemaKind schemaKind
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
USD_API UsdAttribute CreateIncludeRootAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
Definition: type.h:47
virtual USD_API ~UsdCollectionAPI()
Destructor.
static USD_API SdfPathSet ComputeIncludedPaths(const UsdCollectionMembershipQuery &query, const UsdStageWeakPtr &stage, const Usd_PrimFlagsPredicate &pred=UsdPrimDefaultPredicate)
Usd_CollectionMembershipQuery< UsdObjectCollectionExpressionEvaluator > UsdCollectionMembershipQuery
static USD_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
USD_API UsdSchemaKind _GetSchemaKind() const override
UsdCollectionAPI(const UsdPrim &prim=UsdPrim(), const TfToken &name=TfToken())
static USD_API std::vector< UsdCollectionAPI > GetAll(const UsdPrim &prim)
bool IsInExpressionMode() const
USD_API bool IsInRelationshipsMode() const
Definition: value.h:146
Multiple Apply API Schema.
static USD_API std::set< UsdObject > ComputeIncludedObjects(const UsdCollectionMembershipQuery &query, const UsdStageWeakPtr &stage, const Usd_PrimFlagsPredicate &pred=UsdPrimDefaultPredicate)
USD_API UsdRelationship GetIncludesRel() const
USD_API bool ExcludePath(const SdfPath &pathToExclude) const
UsdCollectionAPI(const UsdSchemaBase &schemaObj, const TfToken &name)
static USD_API bool CanContainPropertyName(const TfToken &name)