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 std::vector<UsdCollectionAPI>
236  GetAll(const UsdPrim &prim);
237 
240  USD_API
241  static bool
242  IsSchemaPropertyBaseName(const TfToken &baseName);
243 
247  USD_API
248  static bool
249  IsCollectionAPIPath(const SdfPath &path, TfToken *name);
250 
267  USD_API
268  static bool
269  CanApply(const UsdPrim &prim, const TfToken &name,
270  std::string *whyNot=nullptr);
271 
291  USD_API
292  static UsdCollectionAPI
293  Apply(const UsdPrim &prim, const TfToken &name);
294 
295 protected:
299  USD_API
300  UsdSchemaKind _GetSchemaKind() const override;
301 
302 private:
303  // needs to invoke _GetStaticTfType.
304  friend class UsdSchemaRegistry;
305  USD_API
306  static const TfType &_GetStaticTfType();
307 
308  static bool _IsTypedSchema();
309 
310  // override SchemaBase virtuals.
311  USD_API
312  const TfType &_GetTfType() const override;
313 
314 public:
315  // --------------------------------------------------------------------- //
316  // EXPANSIONRULE
317  // --------------------------------------------------------------------- //
328  USD_API
330 
336  USD_API
337  UsdAttribute CreateExpansionRuleAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
338 
339 public:
340  // --------------------------------------------------------------------- //
341  // INCLUDEROOT
342  // --------------------------------------------------------------------- //
354  USD_API
356 
362  USD_API
363  UsdAttribute CreateIncludeRootAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
364 
365 public:
366  // --------------------------------------------------------------------- //
367  // INCLUDES
368  // --------------------------------------------------------------------- //
375  USD_API
377 
380  USD_API
382 
383 public:
384  // --------------------------------------------------------------------- //
385  // EXCLUDES
386  // --------------------------------------------------------------------- //
400  USD_API
402 
405  USD_API
407 
408 public:
409  // ===================================================================== //
410  // Feel free to add custom code below this line, it will be preserved by
411  // the code generator.
412  //
413  // Just remember to:
414  // - Close the class declaration with };
415  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
416  // - Close the include guard with #endif
417  // ===================================================================== //
418  // --(BEGIN CUSTOM CODE)--
419 
420 public:
423  USD_API
424  static UsdCollectionAPI GetCollection(const UsdStagePtr &stage,
425  const SdfPath &collectionPath);
426 
429  USD_API
430  static UsdCollectionAPI GetCollection(const UsdPrim &prim,
431  const TfToken &name);
432 
435  USD_API
436  static std::vector<UsdCollectionAPI> GetAllCollections(const UsdPrim &prim);
437 
444  USD_API
445  SdfPath GetCollectionPath() const;
446 
451  USD_API
453  const UsdPrim &prim,
454  const TfToken &collectionName);
455 
456  // Convenient alias for UsdCollectionMembershipQuery object
457  using MembershipQuery = UsdCollectionMembershipQuery;
458 
461  USD_API
463 
466  USD_API
468 
476  USD_API
477  bool HasNoIncludedPaths() const;
478 
484  USD_API
485  static std::set<UsdObject> ComputeIncludedObjects(
486  const UsdCollectionMembershipQuery &query,
487  const UsdStageWeakPtr &stage,
488  const Usd_PrimFlagsPredicate &pred=UsdPrimDefaultPredicate);
489 
495  USD_API
496  static SdfPathSet ComputeIncludedPaths(
497  const UsdCollectionMembershipQuery &query,
498  const UsdStageWeakPtr &stage,
499  const Usd_PrimFlagsPredicate &pred=UsdPrimDefaultPredicate);
500 
502 
510 
521  USD_API
522  bool IncludePath(const SdfPath &pathToInclude) const;
523 
536  USD_API
537  bool ExcludePath(const SdfPath &pathToExclude) const;
538 
540 
548  USD_API
549  bool Validate(std::string *reason) const;
550 
556  USD_API
557  bool ResetCollection() const;
558 
564  USD_API
565  bool BlockCollection() const;
566 
569  USD_API
570  static bool CanContainPropertyName(const TfToken &name);
571 
572 private:
573 
574  // Returns the name of the property belonging to this collection, given the
575  // base name of the attribute. Eg, if baseName is 'includes', this
576  // returns 'collection:<name>:includes'.
577  TfToken _GetCollectionPropertyName(const TfToken &baseName=TfToken()) const;
578 
579  // Helper method for computing the UsdCollectionMembershipQuery object for
580  // a collection.
581  // This makes recursive calls if the collection includes other collections.
582  // \p chainedCollectionPaths is used to pass in the set of all seen and
583  // included collections in the dependency chain and is used to detect
584  // circular dependencies.
585  // If \p foundCircularDependency is not nullptr, it is set to true if a
586  // circular dependency is detected amongst the included collections.
587  // If it is nullptr, a warning is issued when a circular dependency is
588  // detected.
589  void _ComputeMembershipQueryImpl(
591  const SdfPathSet &chainedCollectionPaths,
592  bool *foundCircularDependency=nullptr) const;
593 };
594 
595 PXR_NAMESPACE_CLOSE_SCOPE
596 
597 #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
static USD_API std::vector< UsdCollectionAPI > GetAll(const UsdPrim &prim)
Return a vector of all named instances of UsdCollectionAPI on the given prim.
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:134
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...