collectionAPI.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 USD_GENERATED_COLLECTIONAPI_H
25 #define USD_GENERATED_COLLECTIONAPI_H
26 
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/usd/api.h"
32 #include "pxr/usd/usd/prim.h"
33 #include "pxr/usd/usd/stage.h"
34 #include "pxr/usd/usd/tokens.h"
35 
37 #include "pxr/usd/usd/primFlags.h"
38 #include "pxr/usd/usd/tokens.h"
39 
40 
41 #include "pxr/base/vt/value.h"
42 
43 #include "pxr/base/gf/vec3d.h"
44 #include "pxr/base/gf/vec3f.h"
45 #include "pxr/base/gf/matrix4d.h"
46 
47 #include "pxr/base/tf/token.h"
48 #include "pxr/base/tf/type.h"
49 
50 PXR_NAMESPACE_OPEN_SCOPE
51 
52 class SdfAssetPath;
53 
54 // -------------------------------------------------------------------------- //
55 // COLLECTIONAPI //
56 // -------------------------------------------------------------------------- //
57 
153 {
154 public:
159 
170  const UsdPrim& prim=UsdPrim(), const TfToken &name=TfToken())
171  : UsdAPISchemaBase(prim, /*instanceName*/ name)
172  { }
173 
179  const UsdSchemaBase& schemaObj, const TfToken &name)
180  : UsdAPISchemaBase(schemaObj, /*instanceName*/ name)
181  { }
182 
184  USD_API
185  virtual ~UsdCollectionAPI();
186 
190  USD_API
191  static const TfTokenVector &
192  GetSchemaAttributeNames(bool includeInherited=true);
193 
199  USD_API
200  static TfTokenVector
201  GetSchemaAttributeNames(bool includeInherited, const TfToken &instanceName);
202 
204  TfToken GetName() const {
205  return _GetInstanceName();
206  }
207 
222  USD_API
223  static UsdCollectionAPI
224  Get(const UsdStagePtr &stage, const SdfPath &path);
225 
228  USD_API
229  static UsdCollectionAPI
230  Get(const UsdPrim &prim, const TfToken &name);
231 
234  USD_API
235  static bool
236  IsSchemaPropertyBaseName(const TfToken &baseName);
237 
241  USD_API
242  static bool
243  IsCollectionAPIPath(const SdfPath &path, TfToken *name);
244 
261  USD_API
262  static bool
263  CanApply(const UsdPrim &prim, const TfToken &name,
264  std::string *whyNot=nullptr);
265 
285  USD_API
286  static UsdCollectionAPI
287  Apply(const UsdPrim &prim, const TfToken &name);
288 
289 protected:
293  USD_API
294  UsdSchemaKind _GetSchemaKind() const override;
295 
296 private:
297  // needs to invoke _GetStaticTfType.
298  friend class UsdSchemaRegistry;
299  USD_API
300  static const TfType &_GetStaticTfType();
301 
302  static bool _IsTypedSchema();
303 
304  // override SchemaBase virtuals.
305  USD_API
306  const TfType &_GetTfType() const override;
307 
308 public:
309  // --------------------------------------------------------------------- //
310  // EXPANSIONRULE
311  // --------------------------------------------------------------------- //
322  USD_API
324 
330  USD_API
331  UsdAttribute CreateExpansionRuleAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
332 
333 public:
334  // --------------------------------------------------------------------- //
335  // INCLUDEROOT
336  // --------------------------------------------------------------------- //
348  USD_API
350 
356  USD_API
357  UsdAttribute CreateIncludeRootAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
358 
359 public:
360  // --------------------------------------------------------------------- //
361  // INCLUDES
362  // --------------------------------------------------------------------- //
369  USD_API
371 
374  USD_API
376 
377 public:
378  // --------------------------------------------------------------------- //
379  // EXCLUDES
380  // --------------------------------------------------------------------- //
394  USD_API
396 
399  USD_API
401 
402 public:
403  // ===================================================================== //
404  // Feel free to add custom code below this line, it will be preserved by
405  // the code generator.
406  //
407  // Just remember to:
408  // - Close the class declaration with };
409  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
410  // - Close the include guard with #endif
411  // ===================================================================== //
412  // --(BEGIN CUSTOM CODE)--
413 
414 public:
417  USD_API
418  static UsdCollectionAPI GetCollection(const UsdStagePtr &stage,
419  const SdfPath &collectionPath);
420 
423  USD_API
424  static UsdCollectionAPI GetCollection(const UsdPrim &prim,
425  const TfToken &name);
426 
428  USD_API
429  static std::vector<UsdCollectionAPI> GetAllCollections(const UsdPrim &prim);
430 
437  USD_API
438  SdfPath GetCollectionPath() const;
439 
444  USD_API
446  const UsdPrim &prim,
447  const TfToken &collectionName);
448 
449  // Convenient alias for UsdCollectionMembershipQuery object
450  using MembershipQuery = UsdCollectionMembershipQuery;
451 
454  USD_API
456 
459  USD_API
461 
469  USD_API
470  bool HasNoIncludedPaths() const;
471 
477  USD_API
478  static std::set<UsdObject> ComputeIncludedObjects(
479  const UsdCollectionMembershipQuery &query,
480  const UsdStageWeakPtr &stage,
481  const Usd_PrimFlagsPredicate &pred=UsdPrimDefaultPredicate);
482 
488  USD_API
489  static SdfPathSet ComputeIncludedPaths(
490  const UsdCollectionMembershipQuery &query,
491  const UsdStageWeakPtr &stage,
492  const Usd_PrimFlagsPredicate &pred=UsdPrimDefaultPredicate);
493 
495 
503 
514  USD_API
515  bool IncludePath(const SdfPath &pathToInclude) const;
516 
529  USD_API
530  bool ExcludePath(const SdfPath &pathToExclude) const;
531 
533 
541  USD_API
542  bool Validate(std::string *reason) const;
543 
549  USD_API
550  bool ResetCollection() const;
551 
557  USD_API
558  bool BlockCollection() const;
559 
562  USD_API
563  static bool CanContainPropertyName(const TfToken &name);
564 
565 private:
566 
567  // Returns the name of the property belonging to this collection, given the
568  // base name of the attribute. Eg, if baseName is 'includes', this
569  // returns 'collection:<name>:includes'.
570  TfToken _GetCollectionPropertyName(const TfToken &baseName=TfToken()) const;
571 
572  // Helper method for computing the UsdCollectionMembershipQuery object for
573  // a collection.
574  // This makes recursive calls if the collection includes other collections.
575  // \p chainedCollectionPaths is used to pass in the set of all seen and
576  // included collections in the dependency chain and is used to detect
577  // circular dependencies.
578  // If \p foundCircularDependency is not nullptr, it is set to true if a
579  // circular dependency is detected amongst the included collections.
580  // If it is nullptr, a warning is issued when a circular dependency is
581  // detected.
582  void _ComputeMembershipQueryImpl(
584  const SdfPathSet &chainedCollectionPaths,
585  bool *foundCircularDependency=nullptr) const;
586 };
587 
588 PXR_NAMESPACE_CLOSE_SCOPE
589 
590 #endif
static USD_API UsdCollectionAPI GetCollection(const UsdStagePtr &stage, const SdfPath &collectionPath)
Returns the collection represented by the given collection path, collectionPath on the given USD stag...
USD_API bool HasNoIncludedPaths() const
Returns true if the collection has nothing included in it.
unspecified UsdPrimDefaultPredicate
The default predicate used for prim traversals in methods like UsdPrim::GetChildren,...
USD_API UsdRelationship CreateIncludesRel() const
See GetIncludesRel(), and also Create vs Get Property Methods for when to use Get vs Create.
USD_API UsdRelationship GetExcludesRel() const
Specifies a list of targets that are excluded below the included paths in this collection.
Represents a flattened view of a collection.
USD_API UsdCollectionMembershipQuery ComputeMembershipQuery() const
Computes and returns a UsdCollectionMembershipQuery object which can be used to query inclusion or ex...
The base class for all API schemas.
Scenegraph object for authoring and retrieving numeric, string, and array valued data,...
Definition: attribute.h:176
USD_API bool ExcludePath(const SdfPath &pathToExclude) const
Excludes or removes the given path, pathToExclude from the collection.
UsdSchemaKind
An enum representing which kind of schema a given schema class belongs to.
Definition: common.h:127
USD_API UsdAttribute GetIncludeRootAttr() const
Boolean attribute indicating whether the pseudo-root path </> should be counted as one of the include...
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:87
UsdCollectionAPI(const UsdPrim &prim=UsdPrim(), const TfToken &name=TfToken())
Construct a UsdCollectionAPI on UsdPrim prim with name name .
static USD_API UsdCollectionAPI Apply(const UsdPrim &prim, const TfToken &name)
Applies this multiple-apply API schema to the given prim along with the given instance name,...
USD_API bool Validate(std::string *reason) const
Validates the collection by checking the following rules:
This is a general purpose API schema, used to describe a collection of heterogeneous objects within t...
USD_API bool BlockCollection() const
Blocks the targets of the includes and excludes relationships of the collection, making it <* empty i...
static USD_API std::vector< UsdCollectionAPI > GetAllCollections(const UsdPrim &prim)
Returns all the named collections on the given USD prim.
static USD_API UsdCollectionAPI Get(const UsdStagePtr &stage, const SdfPath &path)
Return a UsdCollectionAPI holding the prim adhering to this schema at path on stage.
UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a "Prim" as ...
Definition: prim.h:132
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:442
USD_API UsdAttribute CreateIncludeRootAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
See GetIncludeRootAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:290
static USD_API SdfPath GetNamedCollectionPath(const UsdPrim &prim, const TfToken &collectionName)
Returns the canonical path to the collection named, name on the given prim, prim.
static USD_API bool IsSchemaPropertyBaseName(const TfToken &baseName)
Checks if the given name baseName is the base name of a property of CollectionAPI.
A UsdRelationship creates dependencies between scenegraph objects by allowing a prim to target other ...
Definition: relationship.h:128
USD_API UsdAttribute CreateExpansionRuleAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
See GetExpansionRuleAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
static USD_API bool CanApply(const UsdPrim &prim, const TfToken &name, std::string *whyNot=nullptr)
Returns true if this multiple-apply API schema can be applied, with the given instance name,...
TfToken GetName() const
Returns the name of this multiple-apply schema instance.
Contains an asset path and an optional resolved path.
Definition: assetPath.h:47
static USD_API SdfPathSet ComputeIncludedPaths(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 UsdRelationship CreateExcludesRel() const
See GetExcludesRel(), and also Create vs Get Property Methods for when to use Get vs Create.
Multiple Apply API Schema.
static USD_API std::set< UsdObject > ComputeIncludedObjects(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...
UsdCollectionAPI(const UsdSchemaBase &schemaObj, const TfToken &name)
Construct a UsdCollectionAPI on the prim held by schemaObj with name name.
USD_API bool ResetCollection() const
Resets the collection by clearing both the includes and excludes targets of the collection in the cur...
TfType represents a dynamic runtime type.
Definition: type.h:64
USD_API bool IncludePath(const SdfPath &pathToInclude) const
Includes or adds the given path, pathToInclude in the collection.
Singleton registry that provides access to schema type information and the prim definitions for regis...
USD_API UsdRelationship GetIncludesRel() const
Specifies a list of targets that are included in the collection.
virtual USD_API ~UsdCollectionAPI()
Destructor.
USD_API SdfPath GetCollectionPath() const
Returns the canonical path that represents this collection.
USD_API UsdSchemaKind _GetSchemaKind() const override
Returns the kind of schema this class belongs to.
static const UsdSchemaKind schemaKind
Compile time constant representing what kind of schema this class is.
The base class for all schema types in Usd.
Definition: schemaBase.h:56
static USD_API bool IsCollectionAPIPath(const SdfPath &path, TfToken *name)
Checks if the given path path is of an API schema of type CollectionAPI.
const TfToken & _GetInstanceName() const
Returns the instance name of the API schema object belonging to a multiple-apply API schema.
Provides a container which may hold any type, and provides introspection and iteration over array typ...
Definition: value.h:166
TfToken class for efficient string referencing and hashing, plus conversions to and from stl string c...
static USD_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor cl...
static USD_API bool CanContainPropertyName(const TfToken &name)
Test whether a given name contains the "collection:" prefix.
USD_API UsdAttribute GetExpansionRuleAttr() const
Specifies how the paths that are included in the collection must be expanded to determine its members...