HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
prim.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 PXR_USD_USD_PRIM_H
25 #define PXR_USD_USD_PRIM_H
26 
27 /// \file usd/prim.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/usd/api.h"
31 #include "pxr/usd/usd/common.h"
32 #include "pxr/usd/usd/object.h"
33 #include "pxr/usd/usd/primFlags.h"
34 
35 #include "pxr/usd/sdf/schema.h"
36 #include "pxr/base/trace/trace.h"
37 
39 #include "pxr/base/tf/refBase.h"
40 #include "pxr/base/tf/token.h"
41 #include "pxr/base/tf/weakBase.h"
42 
43 #include "pxr/usd/sdf/path.h"
44 
45 #include <hboost/iterator/iterator_adaptor.hpp>
46 #include <hboost/range/iterator_range.hpp>
47 
48 #include <string>
49 #include <type_traits>
50 #include <vector>
51 
53 
54 class UsdPrim;
55 class UsdPrimDefinition;
56 class UsdPrimRange;
57 class Usd_PrimData;
58 
59 class UsdAttribute;
60 class UsdRelationship;
61 class UsdPayloads;
62 class UsdReferences;
63 class UsdSchemaBase;
64 class UsdAPISchemaBase;
65 class UsdInherits;
66 class UsdSpecializes;
67 class UsdVariantSets;
68 class UsdVariantSet;
69 
70 class SdfPayload;
71 
73 typedef hboost::iterator_range<UsdPrimSiblingIterator> UsdPrimSiblingRange;
74 
76 typedef hboost::iterator_range<UsdPrimSubtreeIterator> UsdPrimSubtreeRange;
77 
78 /// \class UsdPrim
79 ///
80 /// UsdPrim is the sole persistent scenegraph object on a UsdStage, and
81 /// is the embodiment of a "Prim" as described in the <em>Universal Scene
82 /// Description Composition Compendium</em>
83 ///
84 /// A UsdPrim is the principal container of other types of scene description.
85 /// It provides API for accessing and creating all of the contained kinds
86 /// of scene description, which include:
87 /// \li UsdVariantSets - all VariantSets on the prim (GetVariantSets(), GetVariantSet())
88 /// \li UsdReferences - all references on the prim (GetReferences())
89 /// \li UsdInherits - all inherits on the prim (GetInherits())
90 /// \li UsdSpecializes - all specializes on the prim (GetSpecializes())
91 ///
92 /// As well as access to the API objects for properties contained within the
93 /// prim - UsdPrim as well as all of the following classes are subclasses
94 /// of UsdObject:
95 /// \li UsdProperty - generic access to all attributes and relationships.
96 /// A UsdProperty can be queried and cast to a UsdAttribute or UsdRelationship
97 /// using UsdObject::Is<>() and UsdObject::As<>(). (GetPropertyNames(),
98 /// GetProperties(), GetPropertiesInNamespace(), GetPropertyOrder(),
99 /// SetPropertyOrder())
100 /// \li UsdAttribute - access to default and timesampled attribute values, as
101 /// well as value resolution information, and attribute-specific metadata
102 /// (CreateAttribute(), GetAttribute(), GetAttributes(), HasAttribute())
103 /// \li UsdRelationship - access to authoring and resolving relationships
104 /// to other prims and properties (CreateRelationship(), GetRelationship(),
105 /// GetRelationships(), HasRelationship())
106 ///
107 /// UsdPrim also provides access to iteration through its prim children,
108 /// optionally making use of the \ref primFlags.h "prim predicates facility"
109 /// (GetChildren(), GetAllChildren(), GetFilteredChildren()).
110 ///
111 /// \section Lifetime Management
112 ///
113 /// Clients acquire UsdPrim objects, which act like weak/guarded pointers
114 /// to persistent objects owned and managed by their originating UsdStage.
115 /// We provide the following guarantees for a UsdPrim acquired via
116 /// UsdStage::GetPrimAtPath() or UsdStage::OverridePrim() or
117 /// UsdStage::DefinePrim():
118 /// \li As long as no further mutations to the structure of the UsdStage
119 /// are made, the UsdPrim will still be valid. Loading and
120 /// Unloading are considered structural mutations.
121 /// \li When the UsdStage's structure \em is mutated, the thread performing
122 /// the mutation will receive a UsdNotice::ObjectsChanged notice
123 /// after the stage has been reconfigured, which provides details as to
124 /// what prims may have been created or destroyed, and what prims
125 /// may simply have changed in some structural way.
126 ///
127 /// Prim access in "reader" threads should be limited to GetPrimAtPath(), which
128 /// will never cause a mutation to the Stage or its layers.
129 ///
130 /// Please refer to \ref UsdNotice for a listing of
131 /// the events that could cause UsdNotice::ObjectsChanged to be emitted.
132 class UsdPrim : public UsdObject
133 {
134 public:
135  /// Convenience typedefs.
138 
139  /// Convenience typedefs.
142 
143  /// Construct an invalid prim.
145 
146  /// Return the prim's full type info composed from its type name, applied
147  /// API schemas, and any fallback types defined on the stage for
148  /// unrecognized prim type names. The returned type structure contains the
149  /// "true" schema type used to create this prim's prim definition and answer
150  /// the IsA query. This value is cached and efficient to query.
151  /// \sa GetTypeName
152  /// \sa GetAppliedSchemas
153  /// \sa \ref Usd_OM_FallbackPrimTypes
155  return _Prim()->GetPrimTypeInfo();
156  }
157 
158  /// Return this prim's definition based on the prim's type if the type
159  /// is a registered prim type. Returns an empty prim definition if it is
160  /// not.
162  return _Prim()->GetPrimDefinition();
163  }
164 
165  /// Return this prim's composed specifier.
166  SdfSpecifier GetSpecifier() const { return _Prim()->GetSpecifier(); };
167 
168  /// Return all the authored SdfPrimSpecs that may contain opinions for this
169  /// prim in order from strong to weak.
170  ///
171  /// This does not include all the places where contributing prim specs could
172  /// potentially be created; rather, it includes only those prim specs that
173  /// already exist. To discover all the places that prim specs could be
174  /// authored that would contribute opinions, see
175  /// \ref "Composition Structure"
176  ///
177  /// \note Use this method for debugging and diagnostic purposes. It is
178  /// **not** advisable to retain a PrimStack for expedited metadata value
179  /// resolution, since not all metadata resolves with simple "strongest
180  /// opinion wins" semantics.
181  USD_API
182  SdfPrimSpecHandleVector GetPrimStack() const;
183 
184  /// Author an opinion for this Prim's specifier at the current edit
185  /// target.
186  bool SetSpecifier(SdfSpecifier specifier) const {
187  return SetMetadata(SdfFieldKeys->Specifier, specifier);
188  }
189 
190  /// Return this prim's composed type name. This value is cached and is
191  /// efficient to query.
192  /// Note that this is just the composed type name as authored and may not
193  /// represent the full type of the prim and its prim definition. If you
194  /// need to reason about the actual type of the prim, use GetPrimTypeInfo
195  /// instead as it accounts for recognized schemas, applied API schemas,
196  /// fallback types, etc.
197  const TfToken &GetTypeName() const { return _Prim()->GetTypeName(); };
198 
199  /// Author this Prim's typeName at the current EditTarget.
200  bool SetTypeName(const TfToken & typeName) const {
201  return SetMetadata(SdfFieldKeys->TypeName, typeName);
202  }
203 
204  /// Clear the opinion for this Prim's typeName at the current edit
205  /// target.
206  bool ClearTypeName() const {
207  return ClearMetadata(SdfFieldKeys->TypeName);
208  }
209 
210  /// Return true if a typeName has been authored.
211  bool HasAuthoredTypeName() const {
212  return HasAuthoredMetadata(SdfFieldKeys->TypeName);
213  }
214 
215  /// Return true if this prim is active, meaning neither it nor any of its
216  /// ancestors have active=false. Return false otherwise.
217  ///
218  /// See \ref Usd_ActiveInactive for what it means for a prim to be active.
219  bool IsActive() const { return _Prim()->IsActive(); }
220 
221  /// Author 'active' metadata for this prim at the current EditTarget.
222  ///
223  /// See \ref Usd_ActiveInactive for the effects of activating or deactivating
224  /// a prim.
225  bool SetActive(bool active) const {
226  return SetMetadata(SdfFieldKeys->Active, active);
227  }
228 
229  /// Remove the authored 'active' opinion at the current EditTarget. Do
230  /// nothing if there is no authored opinion.
231  ///
232  /// See \ref Usd_ActiveInactive for the effects of activating or deactivating
233  /// a prim.
234  bool ClearActive() const {
235  return ClearMetadata(SdfFieldKeys->Active);
236  }
237 
238  /// Return true if this prim has an authored opinion for 'active', false
239  /// otherwise.
240  ///
241  /// See \ref Usd_ActiveInactive for what it means for a prim to be active.
242  bool HasAuthoredActive() const {
243  return HasAuthoredMetadata(SdfFieldKeys->Active);
244  }
245 
246  /// Return true if this prim is active, and \em either it is loadable and
247  /// it is loaded, \em or its nearest loadable ancestor is loaded, \em or it
248  /// has no loadable ancestor; false otherwise.
249  bool IsLoaded() const { return _Prim()->IsLoaded(); }
250 
251  /// Return true if this prim is a model based on its kind metadata, false
252  /// otherwise.
253  bool IsModel() const { return _Prim()->IsModel(); }
254 
255  /// Return true if this prim is a model group based on its kind metadata,
256  /// false otherwise. If this prim is a group, it is also necessarily a
257  /// model.
258  bool IsGroup() const { return _Prim()->IsGroup(); }
259 
260  /// Return true if this prim or any of its ancestors is a class.
261  bool IsAbstract() const { return _Prim()->IsAbstract(); }
262 
263  /// Return true if this prim and all its ancestors have defining specifiers,
264  /// false otherwise. \sa SdfIsDefiningSpecifier.
265  bool IsDefined() const { return _Prim()->IsDefined(); }
266 
267  /// Return true if this prim has a specifier of type SdfSpecifierDef
268  /// or SdfSpecifierClass. \sa SdfIsDefiningSpecifier
269  bool HasDefiningSpecifier() const {
270  return _Prim()->HasDefiningSpecifier();
271  }
272 
273  /// Return a vector containing the names of API schemas which have
274  /// been applied to this prim. This includes both the authored API schemas
275  /// applied using the Apply() method on the particular schema class as
276  /// well as any built-in API schemas that are automatically included
277  /// through the prim type's prim definition.
278  /// To get only the authored API schemas use GetPrimTypeInfo instead.
279  USD_API
281 
282  /// Alias for the "predicate" function parameter passed into the various
283  /// Get{Authored}{PropertyNames,Properties} methods.
284  using PropertyPredicateFunc =
285  std::function<bool (const TfToken &propertyName)>;
286 
287  /// Return all of this prim's property names (attributes and relationships),
288  /// including all builtin properties.
289  ///
290  /// If a valid \p predicate is passed in, then only properties whose names
291  /// pass the predicate are included in the result. This is useful if the
292  /// client is interested only in a subset of properties on the prim. For
293  /// example, only the ones in a given namespace or only the ones needed to
294  /// compute a value.
295  ///
296  /// \sa GetAuthoredPropertyNames()
297  /// \sa UsdProperty::IsAuthored()
298  USD_API
300  const PropertyPredicateFunc &predicate={}) const;
301 
302  /// Return this prim's property names (attributes and relationships) that
303  /// have authored scene description, ordered according to the strongest
304  /// propertyOrder statement in scene description if one exists, otherwise
305  /// ordered according to TfDictionaryLessThan.
306  ///
307  /// If a valid \p predicate is passed in, then only the authored properties
308  /// whose names pass the predicate are included in the result. This is
309  /// useful if the client is interested only in a subset of authored
310  /// properties on the prim. For example, only the ones in a given namespace
311  /// or only the ones needed to compute a value.
312  ///
313  /// \sa GetPropertyNames()
314  /// \sa UsdProperty::IsAuthored()
315  USD_API
317  const PropertyPredicateFunc &predicate={}) const;
318 
319  /// Return all of this prim's properties (attributes and relationships),
320  /// including all builtin properties, ordered by name according to the
321  /// strongest propertyOrder statement in scene description if one exists,
322  /// otherwise ordered according to TfDictionaryLessThan.
323  ///
324  /// If a valid \p predicate is passed in, then only properties whose names
325  /// pass the predicate are included in the result. This is useful if the
326  /// client is interested only in a subset of properties on the prim. For
327  /// example, only the ones in a given namespace or only the ones needed to
328  /// compute a value.
329  ///
330  /// To obtain only either attributes or relationships, use either
331  /// GetAttributes() or GetRelationships().
332  ///
333  /// To determine whether a property is either an attribute or a
334  /// relationship, use the UsdObject::As() and UsdObject::Is() methods in
335  /// C++:
336  ///
337  /// \code
338  /// // Use As<>() to obtain a subclass instance.
339  /// if (UsdAttribute attr = property.As<UsdAttribute>()) {
340  /// // use attribute 'attr'.
341  /// else if (UsdRelationship rel = property.As<UsdRelationship>()) {
342  /// // use relationship 'rel'.
343  /// }
344  ///
345  /// // Use Is<>() to discriminate only.
346  /// if (property.Is<UsdAttribute>()) {
347  /// // property is an attribute.
348  /// }
349  /// \endcode
350  ///
351  /// In Python, use the standard isinstance() function:
352  ///
353  /// \code
354  /// if isinstance(property, Usd.Attribute):
355  /// # property is a Usd.Attribute.
356  /// elif isinstance(property, Usd.Relationship):
357  /// # property is a Usd.Relationship.
358  /// \endcode
359  ///
360  /// \sa GetAuthoredProperties()
361  /// \sa UsdProperty::IsAuthored()
362  USD_API
363  std::vector<UsdProperty> GetProperties(
364  const PropertyPredicateFunc &predicate={}) const;
365 
366  /// Return this prim's properties (attributes and relationships) that have
367  /// authored scene description, ordered by name according to the strongest
368  /// propertyOrder statement in scene description if one exists, otherwise
369  /// ordered according to TfDictionaryLessThan.
370  ///
371  /// If a valid \p predicate is passed in, then only authored properties
372  /// whose names pass the predicate are included in the result. This is
373  /// useful if the client is interested only in a subset of authored
374  /// properties on the prim. For example, only the ones in a given namespace
375  /// or only the ones needed to compute a value.
376  ///
377  /// \sa GetProperties()
378  /// \sa UsdProperty::IsAuthored()
379  USD_API
380  std::vector<UsdProperty> GetAuthoredProperties(
381  const PropertyPredicateFunc &predicate={}) const;
382 
383  /// Return this prim's properties that are inside the given property
384  /// namespace ordered according to the strongest propertyOrder statement in
385  /// scene description if one exists, otherwise ordered according to
386  /// TfDictionaryLessThan.
387  ///
388  /// A \p namespaces argument whose elements are ["ri", "attribute"] will
389  /// return all the properties under the namespace "ri:attribute",
390  /// i.e. "ri:attribute:*". An empty \p namespaces argument is equivalent to
391  /// GetProperties().
392  ///
393  /// For details of namespaced properties, see \ref Usd_Ordering
394  USD_API
395  std::vector<UsdProperty>
396  GetPropertiesInNamespace(const std::vector<std::string> &namespaces) const;
397 
398  /// \overload
399  /// \p namespaces must be an already-concatenated ordered set of namespaces,
400  /// and may or may not terminate with the namespace-separator character. If
401  /// \p namespaces is empty, this method is equivalent to GetProperties().
402  USD_API
403  std::vector<UsdProperty>
404  GetPropertiesInNamespace(const std::string &namespaces) const;
405 
406  /// Like GetPropertiesInNamespace(), but exclude properties that do not have
407  /// authored scene description from the result. See
408  /// UsdProperty::IsAuthored().
409  ///
410  /// For details of namespaced properties, see \ref Usd_Ordering
411  USD_API
412  std::vector<UsdProperty>
414  const std::vector<std::string> &namespaces) const;
415 
416  /// \overload
417  /// \p namespaces must be an already-concatenated ordered set of namespaces,
418  /// and may or may not terminate with the namespace-separator character. If
419  /// \p namespaces is empty, this method is equivalent to
420  /// GetAuthoredProperties().
421  USD_API
422  std::vector<UsdProperty>
423  GetAuthoredPropertiesInNamespace(const std::string &namespaces) const;
424 
425  /// Return the strongest propertyOrder metadata value authored on this prim.
426  USD_API
428 
429  /// Author an opinion for propertyOrder metadata on this prim at the current
430  /// EditTarget.
431  void SetPropertyOrder(const TfTokenVector &order) const {
432  SetMetadata(SdfFieldKeys->PropertyOrder, order);
433  }
434 
435  /// Remove the opinion for propertyOrder metadata on this prim at the current
436  /// EditTarget.
437  void ClearPropertyOrder() const {
438  ClearMetadata(SdfFieldKeys->PropertyOrder);
439  }
440 
441  /// Remove all scene description for the property with the
442  /// given \p propName <em>in the current UsdEditTarget</em>.
443  /// Return true if the property is removed, false otherwise.
444  ///
445  /// Because this method can only remove opinions about the property from
446  /// the current EditTarget, you may generally find it more useful to use
447  /// UsdAttribute::Block(), which will ensure that all values from the
448  /// EditTarget and weaker layers for the property will be ignored.
449  USD_API
450  bool RemoveProperty(const TfToken &propName);
451 
452  /// Return a UsdProperty with the name \a propName. The property
453  /// returned may or may not \b actually exist so it must be checked for
454  /// validity. Suggested use:
455  ///
456  /// \code
457  /// if (UsdProperty myProp = prim.GetProperty("myProp")) {
458  /// // myProp is safe to use.
459  /// // Edits to the owning stage requires subsequent validation.
460  /// } else {
461  /// // myProp was not defined/authored
462  /// }
463  /// \endcode
464  USD_API
465  UsdProperty GetProperty(const TfToken &propName) const;
466 
467  /// Return true if this prim has an property named \p propName, false
468  /// otherwise.
469  USD_API
470  bool HasProperty(const TfToken &propName) const;
471 
472 private:
473  // The non-templated implementation of UsdPrim::IsA using the
474  // TfType system. \p validateSchemaType is provided for python clients
475  // because they can't use compile time assertions on the input type.
476  USD_API
477  bool _IsA(const TfType& schemaType, bool validateSchemaType) const;
478 
479  // The non-templated implementation of UsdPrim::HasAPI using the
480  // TfType system.
481  //
482  // \p validateSchemaType is provided for python clients
483  // because they can't use compile time assertions on the input type.
484  //
485  // \p instanceName is used to determine whether a particular instance
486  // of a multiple-apply API schema has been applied to the prim.
487  USD_API
488  bool _HasAPI(const TfType& schemaType, bool validateSchemaType,
489  const TfToken &instanceName) const;
490 
491  // Private implementation for all ApplyAPI, CanApplyAPI, and RemoveAPI
492  // methods for both single apply and multiple apply APIs. The multiple
493  // apply API methods validate that the instance name is non-empty, but
494  // otherwise all of these methods do no other input validation as the
495  // public methods are expected to have already done either compile time or
496  // runtime validation already.
497  USD_API
498  bool _CanApplyAPI(const TfType& schemaType,
499  std::string *whyNot) const;
500 
501  USD_API
502  bool _CanApplyAPI(const TfType& schemaType,
503  const TfToken& instanceName,
504  std::string *whyNot) const;
505 
506  USD_API
507  bool _ApplyAPI(const TfType& schemaType) const;
508 
509  USD_API
510  bool _ApplyAPI(const TfType& schemaType,
511  const TfToken& instanceName) const;
512 
513  USD_API
514  bool _RemoveAPI(const TfType& schemaType) const;
515 
516  USD_API
517  bool _RemoveAPI(const TfType& schemaType,
518  const TfToken& instanceName) const;
519 
520 public:
521  /// Return true if the prim's schema type, is or inherits schema type T.
522  /// \sa GetPrimTypeInfo
523  /// \sa UsdPrimTypeInfo::GetSchemaType
524  /// \sa \ref Usd_OM_FallbackPrimTypes
525  template <typename T>
526  bool IsA() const {
528  "Provided type must derive UsdSchemaBase.");
529  return _IsA(TfType::Find<T>(), /*validateSchemaType=*/false);
530  };
531 
532  /// Return true if the prim's schema type is or inherits \p schemaType.
533  /// \sa GetPrimTypeInfo
534  /// \sa UsdPrimTypeInfo::GetSchemaType
535  /// \sa \ref Usd_OM_FallbackPrimTypes
536  USD_API
537  bool IsA(const TfType& schemaType) const;
538 
539  /// Return true if the UsdPrim has had an API schema represented by the C++
540  /// class type __T__ applied to it through the Apply() method provided
541  /// on the API schema class.
542  ///
543  /// \p instanceName, if non-empty is used to determine if a particular
544  /// instance of a multiple-apply API schema (eg. UsdCollectionAPI) has been
545  /// applied to the prim. A coding error is issued if a non-empty
546  /// \p instanceName is passed in and __T__ represents a single-apply API
547  /// schema.
548  ///
549  /// __Using HasAPI in C++__
550  /// \code
551  /// UsdPrim prim = stage->OverridePrim("/path/to/prim");
552  /// MyDomainBozAPI = MyDomainBozAPI::Apply(prim);
553  /// assert(prim.HasAPI<MyDomainBozAPI>());
554  ///
555  /// UsdCollectionAPI collAPI = UsdCollectionAPI::Apply(prim,
556  /// /*instanceName*/ TfToken("geom"))
557  /// assert(prim.HasAPI<UsdCollectionAPI>()
558  /// assert(prim.HasAPI<UsdCollectionAPI>(/*instanceName*/ TfToken("geom")))
559  /// \endcode
560  ///
561  /// The python version of this method takes as an argument the TfType
562  /// of the API schema class. Similar validation of the schema type is
563  /// performed in python at run-time and a coding error is issued if
564  /// the given type is not a valid applied API schema.
565  ///
566  /// __Using HasAPI in Python__
567  /// \code{.py}
568  /// prim = stage.OverridePrim("/path/to/prim")
569  /// bozAPI = MyDomain.BozAPI.Apply(prim)
570  /// assert prim.HasAPI(MyDomain.BozAPI)
571  ///
572  /// collAPI = Usd.CollectionAPI.Apply(prim, "geom")
573  /// assert(prim.HasAPI(Usd.CollectionAPI))
574  /// assert(prim.HasAPI(Usd.CollectionAPI, instanceName="geom"))
575  /// \endcode
576  template <typename T>
577  bool HasAPI(const TfToken &instanceName=TfToken()) const {
579  "Provided type must derive UsdAPISchemaBase.");
581  "Provided type must not be UsdAPISchemaBase.");
582  static_assert(
583  (T::schemaKind == UsdSchemaKind::SingleApplyAPI
584  || T::schemaKind == UsdSchemaKind::MultipleApplyAPI),
585  "Provided schema type must be an applied API schema.");
586 
587  if (T::schemaKind != UsdSchemaKind::MultipleApplyAPI
588  && !instanceName.IsEmpty()) {
589  TF_CODING_ERROR("HasAPI: single application API schemas like %s do "
590  "not contain an application instanceName ( %s ).",
591  TfType::GetCanonicalTypeName(typeid(T)).c_str(),
592  instanceName.GetText());
593  return false;
594  }
595 
596  return _HasAPI(TfType::Find<T>(), /*validateSchemaType=*/false,
597  instanceName);
598  }
599 
600  /// Return true if a prim has an API schema with TfType \p schemaType.
601  ///
602  /// \p instanceName, if non-empty is used to determine if a particular
603  /// instance of a multiple-apply API schema (eg. UsdCollectionAPI) has been
604  /// applied to the prim. A coding error is issued if a non-empty
605  /// \p instanceName is passed in and __T__ represents a single-apply API
606  /// schema.
607  USD_API
608  bool HasAPI(const TfType& schemaType,
609  const TfToken& instanceName=TfToken()) const;
610 
611  /// Returns whether a __single-apply__ API schema with the given C++ type
612  /// 'SchemaType' can be applied to this prim. If the return value is false,
613  /// and \p whyNot is provided, the reason the schema cannot be applied is
614  /// written to whyNot.
615  ///
616  /// Whether the schema can be applied is determined by the schema type
617  /// definition which may specify that the API schema can only be applied to
618  /// certain prim types.
619  ///
620  /// The return value of this function only indicates whether it would be
621  /// valid to apply this schema to the prim. It has no bearing on whether
622  /// calling ApplyAPI will be successful or not.
623  template <typename SchemaType>
624  bool CanApplyAPI(std::string *whyNot = nullptr) const {
626  "Provided type must derive UsdAPISchemaBase.");
628  "Provided type must not be UsdAPISchemaBase.");
629  static_assert(SchemaType::schemaKind == UsdSchemaKind::SingleApplyAPI,
630  "Provided schema type must be a single apply API schema.");
631 
632  static const TfType schemaType = TfType::Find<SchemaType>();
633  return _CanApplyAPI(schemaType, whyNot);
634  }
635 
636  /// Non-templated overload of the templated CanApplyAPI above.
637  ///
638  /// This function behaves exactly like the templated CanApplyAPI
639  /// except for the runtime schemaType validation which happens at compile
640  /// time in the templated version. This method is provided for python
641  /// clients. Use of the templated CanApplyAPI is preferred.
642  USD_API
643  bool CanApplyAPI(const TfType& schemaType,
644  std::string *whyNot = nullptr) const;
645 
646  /// Returns whether a __multiple-apply__ API schema with the given C++
647  /// type 'SchemaType' can be applied to this prim with the given
648  /// \p instanceName. If the return value is false, and \p whyNot is
649  /// provided, the reason the schema cannot be applied is written to whyNot.
650  ///
651  /// Whether the schema can be applied is determined by the schema type
652  /// definition which may specify that the API schema can only be applied to
653  /// certain prim types. It also determines whether the instance name is a
654  /// valid instance name for the multiple apply schema.
655  ///
656  /// The return value of this function only indicates whether it would be
657  /// valid to apply this schema to the prim. It has no bearing on whether
658  /// calling ApplyAPI will be successful or not.
659  template <typename SchemaType>
660  bool CanApplyAPI(const TfToken &instanceName,
661  std::string *whyNot = nullptr) const {
663  "Provided type must derive UsdAPISchemaBase.");
665  "Provided type must not be UsdAPISchemaBase.");
666  static_assert(SchemaType::schemaKind == UsdSchemaKind::MultipleApplyAPI,
667  "Provided schema type must be a multiple apply API schema.");
668 
669  static const TfType schemaType = TfType::Find<SchemaType>();
670  return _CanApplyAPI(schemaType, instanceName, whyNot);
671  }
672 
673  /// Non-templated overload of the templated CanApplyAPI above.
674  ///
675  /// This function behaves exactly like the templated CanApplyAPI
676  /// except for the runtime schemaType validation which happens at compile
677  /// time in the templated version. This method is provided for python
678  /// clients. Use of the templated CanApplyAPI is preferred.
679  USD_API
680  bool CanApplyAPI(const TfType& schemaType,
681  const TfToken& instanceName,
682  std::string *whyNot = nullptr) const;
683 
684  /// Applies a __single-apply__ API schema with the given C++ type
685  /// 'SchemaType' to this prim in the current edit target.
686  ///
687  /// This information is stored by adding the API schema's name token to the
688  /// token-valued, listOp metadata \em apiSchemas on this prim.
689  ///
690  /// Returns true upon success or if the API schema is already applied in
691  /// the current edit target.
692  ///
693  /// An error is issued and false returned for any of the following
694  /// conditions:
695  /// \li this prim is not a valid prim for editing
696  /// \li this prim is valid, but cannot be reached or overridden in the
697  /// current edit target
698  /// \li the schema name cannot be added to the apiSchemas listOp metadata
699  template <typename SchemaType>
700  bool ApplyAPI() const {
702  "Provided type must derive UsdAPISchemaBase.");
704  "Provided type must not be UsdAPISchemaBase.");
705  static_assert(SchemaType::schemaKind == UsdSchemaKind::SingleApplyAPI,
706  "Provided schema type must be a single apply API schema.");
707 
708  static const TfType schemaType = TfType::Find<SchemaType>();
709  return _ApplyAPI(schemaType);
710  }
711 
712  /// Non-templated overload of the templated ApplyAPI above.
713  ///
714  /// This function behaves exactly like the templated ApplyAPI
715  /// except for the runtime schemaType validation which happens at compile
716  /// time in the templated version. This method is provided for python
717  /// clients. Use of the templated ApplyAPI is preferred.
718  USD_API
719  bool ApplyAPI(const TfType& schemaType) const;
720 
721  /// Applies a __multiple-apply__ API schema with the given C++ type
722  /// 'SchemaType' and instance name \p instanceName to this prim in the
723  /// current edit target.
724  ///
725  /// This information is stored in the token-valued, listOp metadata
726  /// \em apiSchemas on this prim. For example, if SchemaType is
727  /// 'UsdCollectionAPI' and \p instanceName is 'plasticStuff', the name
728  /// 'CollectionAPI:plasticStuff' is added to the 'apiSchemas' listOp
729  /// metadata.
730  ///
731  /// Returns true upon success or if the API schema is already applied with
732  /// this \p instanceName in the current edit target.
733  ///
734  /// An error is issued and false returned for any of the following
735  /// conditions:
736  /// \li \p instanceName is empty
737  /// \li this prim is not a valid prim for editing
738  /// \li this prim is valid, but cannot be reached or overridden in the
739  /// current edit target
740  /// \li the schema name cannot be added to the apiSchemas listOp metadata
741  template <typename SchemaType>
742  bool ApplyAPI(const TfToken &instanceName) const {
744  "Provided type must derive UsdAPISchemaBase.");
746  "Provided type must not be UsdAPISchemaBase.");
747  static_assert(SchemaType::schemaKind == UsdSchemaKind::MultipleApplyAPI,
748  "Provided schema type must be a multiple apply API schema.");
749 
750  static const TfType schemaType = TfType::Find<SchemaType>();
751  return _ApplyAPI(schemaType, instanceName);
752  }
753 
754  /// Non-templated overload of the templated ApplyAPI above.
755  ///
756  /// This function behaves exactly like the templated ApplyAPI
757  /// except for the runtime schemaType validation which happens at compile
758  /// time in the templated version. This method is provided for python
759  /// clients. Use of the templated ApplyAPI is preferred.
760  USD_API
761  bool ApplyAPI(const TfType& schemaType, const TfToken& instanceName) const;
762 
763  /// Removes a __single-apply__ API schema with the given C++ type
764  /// 'SchemaType' from this prim in the current edit target.
765  ///
766  /// This is done by removing the API schema's name token from the
767  /// token-valued, listOp metadata \em apiSchemas on this prim as well as
768  /// authoring an explicit deletion of schema name from the listOp.
769  ///
770  /// Returns true upon success or if the API schema is already deleted in
771  /// the current edit target.
772  ///
773  /// An error is issued and false returned for any of the following
774  /// conditions:
775  /// \li this prim is not a valid prim for editing
776  /// \li this prim is valid, but cannot be reached or overridden in the
777  /// current edit target
778  /// \li the schema name cannot be deleted in the apiSchemas listOp metadata
779  template <typename SchemaType>
780  bool RemoveAPI() const {
782  "Provided type must derive UsdAPISchemaBase.");
784  "Provided type must not be UsdAPISchemaBase.");
785  static_assert(SchemaType::schemaKind == UsdSchemaKind::SingleApplyAPI,
786  "Provided schema type must be a single apply API schema.");
787 
788  static const TfType schemaType = TfType::Find<SchemaType>();
789  return _RemoveAPI(schemaType);
790  }
791 
792  /// Non-templated overload of the templated RemoveAPI above.
793  ///
794  /// This function behaves exactly like the templated RemoveAPI
795  /// except for the runtime schemaType validation which happens at compile
796  /// time in the templated version. This method is provided for python
797  /// clients. Use of the templated RemoveAPI is preferred.
798  USD_API
799  bool RemoveAPI(const TfType& schemaType) const;
800 
801  /// Removes a __multiple-apply__ API schema with the given C++ type
802  /// 'SchemaType' and instance name \p instanceName from this prim in the
803  /// current edit target.
804  ///
805  /// This is done by removing the instanced schema name token from the
806  /// token-valued, listOp metadata \em apiSchemas on this prim as well as
807  /// authoring an explicit deletion of the name from the listOp. For example,
808  /// if SchemaType is 'UsdCollectionAPI' and \p instanceName is
809  /// 'plasticStuff', the name 'CollectionAPI:plasticStuff' is deleted
810  /// from the 'apiSchemas' listOp metadata.
811  ///
812  /// Returns true upon success or if the API schema with this \p instanceName
813  /// is already deleted in the current edit target.
814  ///
815  /// An error is issued and false returned for any of the following
816  /// conditions:
817  /// \li \p instanceName is empty
818  /// \li this prim is not a valid prim for editing
819  /// \li this prim is valid, but cannot be reached or overridden in the
820  /// current edit target
821  /// \li the schema name cannot be deleted in the apiSchemas listOp metadata
822  template <typename SchemaType>
823  bool RemoveAPI(const TfToken &instanceName) const {
825  "Provided type must derive UsdAPISchemaBase.");
827  "Provided type must not be UsdAPISchemaBase.");
828  static_assert(SchemaType::schemaKind == UsdSchemaKind::MultipleApplyAPI,
829  "Provided schema type must be a multiple apply API schema.");
830 
831  static const TfType schemaType = TfType::Find<SchemaType>();
832  return _RemoveAPI(schemaType, instanceName);
833  }
834 
835  /// Non-templated overload of the templated RemoveAPI above.
836  ///
837  /// This function behaves exactly like the templated RemoveAPI
838  /// except for the runtime schemaType validation which happens at compile
839  /// time in the templated version. This method is provided for python
840  /// clients. Use of the templated RemoveAPI is preferred.
841  USD_API
842  bool RemoveAPI(const TfType& schemaType,
843  const TfToken& instanceName) const;
844 
845  /// Adds the applied API schema name token \p appliedSchemaName to the
846  /// \em apiSchemas metadata for this prim at the current edit target. For
847  /// multiple-apply schemas the name token should include the instance name
848  /// for the applied schema, for example 'CollectionAPI:plasticStuff'.
849  ///
850  /// The name will only be added if the \ref SdfListOp "list operation" at
851  /// the edit target does not already have this applied schema in its
852  /// explicit, prepended, or appended lists and is always added to the end
853  /// of either the prepended or explicit items.
854  ///
855  /// Returns true upon success or if the API schema is already applied in
856  /// the current edit target.
857  ///
858  /// An error is issued and false returned for any of the following
859  /// conditions:
860  /// \li this prim is not a valid prim for editing
861  /// \li this prim is valid, but cannot be reached or overridden in the
862  /// current edit target
863  /// \li the schema name cannot be added to the apiSchemas listOp metadata
864  ///
865  /// Unlike ApplyAPI this method does not require that the name token
866  /// refer to a valid API schema type. ApplyAPI is the preferred method
867  /// for applying valid API schemas.
868  USD_API
869  bool AddAppliedSchema(const TfToken &appliedSchemaName) const;
870 
871  /// Removes the applied API schema name token \p appliedSchemaName from the
872  /// \em apiSchemas metadata for this prim at the current edit target. For
873  /// multiple-apply schemas the name token should include the instance name
874  /// for the applied schema, for example 'CollectionAPI:plasticStuff'
875  ///
876  /// For an explicit \ref SdfListOp "list operation", this removes the
877  /// applied schema name from the explicit items list if it was present. For
878  /// a non-explicit \ref SdfListOp "list operation", this will remove any
879  /// occurrence of the applied schema name from the prepended and appended
880  /// item as well as adding it to the deleted items list.
881  ///
882  /// Returns true upon success or if the API schema is already deleted in
883  /// the current edit target.
884  ///
885  /// An error is issued and false returned for any of the following
886  /// conditions:
887  /// \li this prim is not a valid prim for editing
888  /// \li this prim is valid, but cannot be reached or overridden in the
889  /// current edit target
890  /// \li the schema name cannot be deleted in the apiSchemas listOp metadata
891  ///
892  /// Unlike RemoveAPI this method does not require that the name token
893  /// refer to a valid API schema type. RemoveAPI is the preferred method
894  /// for removing valid API schemas.
895  USD_API
896  bool RemoveAppliedSchema(const TfToken &appliedSchemaName) const;
897 
898  // --------------------------------------------------------------------- //
899  /// \name Prim Children
900  // --------------------------------------------------------------------- //
901 
902  /// Return this prim's direct child named \p name if it has one, otherwise
903  /// return an invalid UsdPrim. Equivalent to:
904  /// \code
905  /// prim.GetStage()->GetPrimAtPath(prim.GetPath().AppendChild(name))
906  /// \endcode
907  USD_API
908  UsdPrim GetChild(const TfToken &name) const;
909 
910  /// Return this prim's active, loaded, defined, non-abstract children as an
911  /// iterable range. Equivalent to:
912  /// \code
913  /// GetFilteredChildren(UsdPrimDefaultPredicate)
914  /// \endcode
915  ///
916  /// See \ref Usd_PrimFlags "Prim predicate flags"
917  /// and #UsdPrimDefaultPredicate for more information.
918  inline SiblingRange GetChildren() const;
919 
920  /// Return all this prim's children as an iterable range.
921  inline SiblingRange GetAllChildren() const;
922 
923  /// Return a subset of all of this prim's children filtered by \p predicate
924  /// as an iterable range. The \p predicate is generated by combining a
925  /// series of prim flag terms with either && or || and !.
926  ///
927  /// Example usage:
928  /// \code
929  /// // Get all active model children.
930  /// GetFilteredChildren(UsdPrimIsActive && UsdPrimIsModel);
931  ///
932  /// // Get all model children that pass the default predicate.
933  /// GetFilteredChildren(UsdPrimDefaultPredicate && UsdPrimIsModel);
934  /// \endcode
935  ///
936  /// If this prim is an instance, no children will be returned unless
937  /// #UsdTraverseInstanceProxies is used to allow instance proxies to be
938  /// returned, or if this prim is itself an instance proxy.
939  ///
940  /// See \ref Usd_PrimFlags "Prim predicate flags"
941  /// and #UsdPrimDefaultPredicate for more information.
942  inline SiblingRange
943  GetFilteredChildren(const Usd_PrimFlagsPredicate &predicate) const;
944 
945  /// Return the names of the child prims in the order they appear when
946  /// iterating over GetChildren.
947  USD_API
949 
950  /// Return the names of the child prims in the order they appear when
951  /// iterating over GetAllChildren.
952  USD_API
954 
955  /// Return the names of the child prims in the order they appear when
956  /// iterating over GetFilteredChildren(\p predicate).
957  USD_API
959  const Usd_PrimFlagsPredicate &predicate) const;
960 
961  /// Return this prim's active, loaded, defined, non-abstract descendants as
962  /// an iterable range. Equivalent to:
963  /// \code
964  /// GetFilteredDescendants(UsdPrimDefaultPredicate)
965  /// \endcode
966  ///
967  /// \note This method is not yet available in python, pending some
968  /// refactoring to make it more feasible.
969  ///
970  /// See \ref Usd_PrimFlags "Prim predicate flags" and
971  /// #UsdPrimDefaultPredicate for more information, UsdStage::Traverse(),
972  /// and \c UsdPrimRange for more general Stage traversal behaviors.
973  inline SubtreeRange GetDescendants() const;
974 
975  /// Return all this prim's descendants as an iterable range.
976  ///
977  /// \note This method is not yet available in python, pending some
978  /// refactoring to make it more feasible.
979  ///
980  /// See \ref Usd_PrimFlags "Prim predicate flags" and
981  /// #UsdPrimDefaultPredicate for more information, UsdStage::Traverse(),
982  /// and \c UsdPrimRange for more general Stage traversal behaviors.
983  inline SubtreeRange GetAllDescendants() const;
984 
985  /// Return a subset of all of this prim's descendants filtered by
986  /// \p predicate as an iterable range. The \p predicate is generated by
987  /// combining a series of prim flag terms with either && or || and !.
988  ///
989  /// Example usage:
990  /// \code
991  /// // Get all active model descendants.
992  /// GetFilteredDescendants(UsdPrimIsActive && UsdPrimIsModel);
993  ///
994  /// // Get all model descendants that pass the default predicate.
995  /// GetFilteredDescendants(UsdPrimDefaultPredicate && UsdPrimIsModel);
996  /// \endcode
997  ///
998  /// If this prim is an instance, no descendants will be returned unless
999  /// #UsdTraverseInstanceProxies is used to allow instance proxies to be
1000  /// returned, or if this prim is itself an instance proxy.
1001  ///
1002  /// \note This method is not yet available in python, pending some
1003  /// refactoring to make it more feasible.
1004  ///
1005  /// See \ref Usd_PrimFlags "Prim predicate flags" and
1006  /// #UsdPrimDefaultPredicate for more information, UsdStage::Traverse(),
1007  /// and \c UsdPrimRange for more general Stage traversal behaviors.
1008  inline SubtreeRange
1009  GetFilteredDescendants(const Usd_PrimFlagsPredicate &predicate) const;
1010 
1011  /// Return the strongest opinion for the metadata used to reorder children
1012  /// of this prim. Due to how reordering of prim children is composed,
1013  /// this value cannot be relied on to get the actual order of the prim's
1014  /// children. Use GetChidrenNames, GetAllChildrenNames,
1015  /// GetFilteredChildrenNames to get the true child order if needed.
1016  USD_API
1018 
1019  /// Author an opinion for the metadata used to reorder children of this
1020  /// prim at the current EditTarget.
1022  SetMetadata(SdfFieldKeys->PrimOrder, order);
1023  }
1024 
1025  /// Remove the opinion for the metadata used to reorder children of this
1026  /// prim at the current EditTarget.
1027  void ClearChildrenReorder() const {
1028  ClearMetadata(SdfFieldKeys->PrimOrder);
1029  }
1030 
1031 public:
1032  // --------------------------------------------------------------------- //
1033  /// \name Parent & Stage
1034  // --------------------------------------------------------------------- //
1035 
1036  /// Return this prim's parent prim. Return an invalid UsdPrim if this is a
1037  /// root prim.
1038  UsdPrim GetParent() const {
1040  SdfPath proxyPrimPath = _ProxyPrimPath();
1041  Usd_MoveToParent(prim, proxyPrimPath);
1042  return UsdPrim(prim, proxyPrimPath);
1043  }
1044 
1045  /// Return this prim's next active, loaded, defined, non-abstract sibling
1046  /// if it has one, otherwise return an invalid UsdPrim. Equivalent to:
1047  /// \code
1048  /// GetFilteredNextSibling(UsdPrimDefaultPredicate)
1049  /// \endcode
1050  ///
1051  /// See \ref Usd_PrimFlags "Prim predicate flags"
1052  /// and #UsdPrimDefaultPredicate for more information.
1053  USD_API
1054  UsdPrim GetNextSibling() const;
1055 
1056  /// Return this prim's next sibling that matches \p predicate if it has one,
1057  /// otherwise return the invalid UsdPrim.
1058  ///
1059  /// See \ref Usd_PrimFlags "Prim predicate flags"
1060  /// and #UsdPrimDefaultPredicate for more information.
1061  USD_API
1063  const Usd_PrimFlagsPredicate &predicate) const;
1064 
1065  /// Returns true if the prim is the pseudo root.
1066  ///
1067  /// Equivalent to
1068  /// \code
1069  /// prim.GetPath() == SdfPath::AbsoluteRootPath()
1070  /// \endcode
1071  USD_API
1072  bool IsPseudoRoot() const;
1073 
1074  /// Returns the prim at \p path on the same stage as this prim.
1075  /// If path is is relative, it will be anchored to the path of this prim.
1076  /// \sa UsdStage::GetPrimAtPath(const SdfPath&) const
1077  USD_API UsdPrim GetPrimAtPath(const SdfPath& path) const;
1078 
1079  /// Returns the object at \p path on the same stage as this prim.
1080  /// If path is is relative, it will be anchored to the path of this prim.
1081  /// \sa UsdStage::GetObjectAtPath(const SdfPath&) const
1083 
1084  /// Returns the property at \p path on the same stage as this prim.
1085  /// If path is relative, it will be anchored to the path of this prim.
1086  ///
1087  /// \note There is no guarantee that this method returns a property on
1088  /// this prim. This is only guaranteed if path is a purely relative
1089  /// property path.
1090  /// \sa GetProperty(const TfToken&) const
1091  /// \sa UsdStage::GetPropertyAtPath(const SdfPath&) const
1093 
1094  /// Returns the attribute at \p path on the same stage as this prim.
1095  /// If path is relative, it will be anchored to the path of this prim.
1096  ///
1097  /// \note There is no guarantee that this method returns an attribute on
1098  /// this prim. This is only guaranteed if path is a purely relative
1099  /// property path.
1100  /// \sa GetAttribute(const TfToken&) const
1101  /// \sa UsdStage::GetAttributeAtPath(const SdfPath&) const
1103 
1104  /// Returns the relationship at \p path on the same stage as this prim.
1105  /// If path is relative, it will be anchored to the path of this prim.
1106  ///
1107  /// \note There is no guarantee that this method returns a relationship on
1108  /// this prim. This is only guaranteed if path is a purely relative
1109  /// property path.
1110  /// \sa GetRelationship(const TfToken&) const
1111  /// \sa UsdStage::GetRelationshipAtPath(const SdfPath&) const
1113 
1114  // --------------------------------------------------------------------- //
1115  /// \name Variants
1116  // --------------------------------------------------------------------- //
1117 
1118  /// Return a UsdVariantSets object representing all the VariantSets
1119  /// present on this prim.
1120  ///
1121  /// The returned object also provides the API for adding new VariantSets
1122  /// to the prim.
1123  USD_API
1125 
1126  /// Retrieve a specifically named VariantSet for editing or constructing
1127  /// a UsdEditTarget.
1128  ///
1129  /// This is a shortcut for
1130  /// \code
1131  /// prim.GetVariantSets().GetVariantSet(variantSetName)
1132  /// \endcode
1133  USD_API
1134  UsdVariantSet GetVariantSet(const std::string& variantSetName) const;
1135 
1136  /// Return true if this prim has any authored VariantSets.
1137  ///
1138  /// \note this connotes only the *existence* of one of more VariantSets,
1139  /// *not* that such VariantSets necessarily contain any variants or
1140  /// variant opinions.
1141  USD_API
1142  bool HasVariantSets() const;
1143 
1144  // --------------------------------------------------------------------- //
1145  /// \name Attributes
1146  // --------------------------------------------------------------------- //
1147 
1148  /// Author scene description for the attribute named \a attrName at the
1149  /// current EditTarget if none already exists. Return a valid attribute if
1150  /// scene description was successfully authored or if it already existed,
1151  /// return invalid attribute otherwise. Note that the supplied \a typeName
1152  /// and \a custom arguments are only used in one specific case. See below
1153  /// for details.
1154  ///
1155  /// Suggested use:
1156  /// \code
1157  /// if (UsdAttribute myAttr = prim.CreateAttribute(...)) {
1158  /// // success.
1159  /// }
1160  /// \endcode
1161  ///
1162  /// To call this, GetPrim() must return a valid prim.
1163  ///
1164  /// - If a spec for this attribute already exists at the current edit
1165  /// target, do nothing.
1166  ///
1167  /// - If a spec for \a attrName of a different spec type (e.g. a
1168  /// relationship) exists at the current EditTarget, issue an error.
1169  ///
1170  /// - If \a name refers to a builtin attribute according to the prim's
1171  /// definition, author an attribute spec with required metadata from the
1172  /// definition.
1173  ///
1174  /// - If \a name refers to a builtin relationship, issue an error.
1175  ///
1176  /// - If there exists an absolute strongest authored attribute spec for
1177  /// \a attrName, author an attribute spec at the current EditTarget by
1178  /// copying required metadata from that strongest spec.
1179  ///
1180  /// - If there exists an absolute strongest authored relationship spec for
1181  /// \a attrName, issue an error.
1182  ///
1183  /// - Otherwise author an attribute spec at the current EditTarget using
1184  /// the provided \a typeName and \a custom for the required metadata fields.
1185  /// Note that these supplied arguments are only ever used in this particular
1186  /// circumstance, in all other cases they are ignored.
1187  USD_API
1188  UsdAttribute
1189  CreateAttribute(const TfToken& name,
1190  const SdfValueTypeName &typeName,
1191  bool custom,
1192  SdfVariability variability = SdfVariabilityVarying) const;
1193  /// \overload
1194  /// Create a custom attribute with \p name, \p typeName and \p variability.
1195  USD_API
1196  UsdAttribute
1197  CreateAttribute(const TfToken& name,
1198  const SdfValueTypeName &typeName,
1199  SdfVariability variability = SdfVariabilityVarying) const;
1200 
1201  /// \overload
1202  /// This overload of CreateAttribute() accepts a vector of name components
1203  /// used to construct a \em namespaced property name. For details, see
1204  /// \ref Usd_Ordering
1205  USD_API
1207  const std::vector<std::string> &nameElts,
1208  const SdfValueTypeName &typeName,
1209  bool custom,
1210  SdfVariability variability = SdfVariabilityVarying) const;
1211  /// \overload
1212  /// Create a custom attribute with \p nameElts, \p typeName, and
1213  /// \p variability.
1214  USD_API
1216  const std::vector<std::string> &nameElts,
1217  const SdfValueTypeName &typeName,
1218  SdfVariability variability = SdfVariabilityVarying) const;
1219 
1220  /// Like GetProperties(), but exclude all relationships from the result.
1221  USD_API
1222  std::vector<UsdAttribute> GetAttributes() const;
1223 
1224  /// Like GetAttributes(), but exclude attributes without authored scene
1225  /// description from the result. See UsdProperty::IsAuthored().
1226  USD_API
1227  std::vector<UsdAttribute> GetAuthoredAttributes() const;
1228 
1229  /// Return a UsdAttribute with the name \a attrName. The attribute
1230  /// returned may or may not \b actually exist so it must be checked for
1231  /// validity. Suggested use:
1232  ///
1233  /// \code
1234  /// if (UsdAttribute myAttr = prim.GetAttribute("myAttr")) {
1235  /// // myAttr is safe to use.
1236  /// // Edits to the owning stage requires subsequent validation.
1237  /// } else {
1238  /// // myAttr was not defined/authored
1239  /// }
1240  /// \endcode
1241  USD_API
1242  UsdAttribute GetAttribute(const TfToken& attrName) const;
1243 
1244  /// Return true if this prim has an attribute named \p attrName, false
1245  /// otherwise.
1246  USD_API
1247  bool HasAttribute(const TfToken& attrName) const;
1248 
1249  /// Search the prim subtree rooted at this prim for attributes for which
1250  /// \p predicate returns true, collect their connection source paths and
1251  /// return them in an arbitrary order. If \p recurseOnSources is true,
1252  /// act as if this function was invoked on the connected prims and owning
1253  /// prims of connected properties also and return the union.
1254  USD_API
1257  std::function<bool (UsdAttribute const &)> const &pred = nullptr,
1258  bool recurseOnSources = false) const;
1259 
1260  // --------------------------------------------------------------------- //
1261  /// \name Relationships
1262  // --------------------------------------------------------------------- //
1263 
1264  /// Author scene description for the relationship named \a relName at the
1265  /// current EditTarget if none already exists. Return a valid relationship
1266  /// if scene description was successfully authored or if it already existed,
1267  /// return an invalid relationship otherwise.
1268  ///
1269  /// Suggested use:
1270  /// \code
1271  /// if (UsdRelationship myRel = prim.CreateRelationship(...)) {
1272  /// // success.
1273  /// }
1274  /// \endcode
1275  ///
1276  /// To call this, GetPrim() must return a valid prim.
1277  ///
1278  /// - If a spec for this relationship already exists at the current edit
1279  /// target, do nothing.
1280  ///
1281  /// - If a spec for \a relName of a different spec type (e.g. an
1282  /// attribute) exists at the current EditTarget, issue an error.
1283  ///
1284  /// - If \a name refers to a builtin relationship according to the prim's
1285  /// definition, author a relationship spec with required metadata from the
1286  /// definition.
1287  ///
1288  /// - If \a name refers to a builtin attribute, issue an error.
1289  ///
1290  /// - If there exists an absolute strongest authored relationship spec for
1291  /// \a relName, author a relationship spec at the current EditTarget by
1292  /// copying required metadata from that strongest spec.
1293  ///
1294  /// - If there exists an absolute strongest authored attribute spec for \a
1295  /// relName, issue an error.
1296  ///
1297  /// - Otherwise author a uniform relationship spec at the current
1298  /// EditTarget, honoring \p custom .
1299  ///
1300  USD_API
1302  bool custom=true) const;
1303 
1304  /// \overload
1305  /// This overload of CreateRelationship() accepts a vector of
1306  /// name components used to construct a \em namespaced property name.
1307  /// For details, see \ref Usd_Ordering
1308  USD_API
1309  UsdRelationship CreateRelationship(const std::vector<std::string> &nameElts,
1310  bool custom=true)
1311  const;
1312 
1313  /// Like GetProperties(), but exclude all attributes from the result.
1314  USD_API
1315  std::vector<UsdRelationship> GetRelationships() const;
1316 
1317  /// Like GetRelationships(), but exclude relationships without authored
1318  /// scene description from the result. See UsdProperty::IsAuthored().
1319  USD_API
1320  std::vector<UsdRelationship> GetAuthoredRelationships() const;
1321 
1322  /// Return a UsdRelationship with the name \a relName. The relationship
1323  /// returned may or may not \b actually exist so it must be checked for
1324  /// validity. Suggested use:
1325  ///
1326  /// \code
1327  /// if (UsdRelationship myRel = prim.GetRelationship("myRel")) {
1328  /// // myRel is safe to use.
1329  /// // Edits to the owning stage requires subsequent validation.
1330  /// } else {
1331  /// // myRel was not defined/authored
1332  /// }
1333  /// \endcode
1334  USD_API
1335  UsdRelationship GetRelationship(const TfToken& relName) const;
1336 
1337  /// Return true if this prim has a relationship named \p relName, false
1338  /// otherwise.
1339  USD_API
1340  bool HasRelationship(const TfToken& relName) const;
1341 
1342  /// Search the prim subtree rooted at this prim for relationships for which
1343  /// \p predicate returns true, collect their target paths and return them in
1344  /// an arbitrary order. If \p recurseOnTargets is true, act as if this
1345  /// function was invoked on the targeted prims and owning prims of targeted
1346  /// properties also (but not of forwarding relationships) and return the
1347  /// union.
1348  USD_API
1351  std::function<bool (UsdRelationship const &)> const &pred = nullptr,
1352  bool recurseOnTargets = false) const;
1353 
1354  // --------------------------------------------------------------------- //
1355  /// \name Payload Authoring
1356  /// \deprecated
1357  /// This API is now deprecated. Please use the HasAuthoredPayloads and the
1358  /// UsdPayloads API returned from GetPayloads() to query and author payloads
1359  /// instead.
1360  /// @{
1361  // --------------------------------------------------------------------- //
1362 
1363  /// \deprecated
1364  /// Clears the payload at the current EditTarget for this prim. Return false
1365  /// if the payload could not be cleared.
1366  USD_API
1367  bool ClearPayload() const;
1368 
1369  /// \deprecated
1370  /// Return true if a payload is present on this prim.
1371  ///
1372  /// \sa \ref Usd_Payloads
1373  USD_API
1374  bool HasPayload() const;
1375 
1376  /// \deprecated
1377  /// Author payload metadata for this prim at the current edit
1378  /// target. Return true on success, false if the value could not be set.
1379  ///
1380  /// \sa \ref Usd_Payloads
1381  USD_API
1382  bool SetPayload(const SdfPayload& payload) const;
1383 
1384  /// \deprecated
1385  /// Shorthand for SetPayload(SdfPayload(assetPath, primPath)).
1386  USD_API
1387  bool SetPayload(
1388  const std::string& assetPath, const SdfPath& primPath) const;
1389 
1390  /// \deprecated
1391  /// Shorthand for SetPayload(SdfPayload(layer->GetIdentifier(),
1392  /// primPath)).
1393  USD_API
1394  bool SetPayload(const SdfLayerHandle& layer, const SdfPath& primPath) const;
1395 
1396  /// @}
1397 
1398  // --------------------------------------------------------------------- //
1399  /// \name Payloads, Load and Unload
1400  // --------------------------------------------------------------------- //
1401 
1402  /// Return a UsdPayloads object that allows one to add, remove, or
1403  /// mutate payloads <em>at the currently set UsdEditTarget</em>.
1404  ///
1405  /// While the UsdPayloads object has no methods for \em listing the
1406  /// currently authored payloads on a prim, one can use a
1407  /// UsdPrimCompositionQuery to query the payload arcs that are composed
1408  /// by this prim.
1409  USD_API
1410  UsdPayloads GetPayloads() const;
1411 
1412  /// Return true if this prim has any authored payloads.
1413  USD_API
1414  bool HasAuthoredPayloads() const;
1415 
1416  /// Load this prim, all its ancestors, and by default all its descendants.
1417  /// If \p loadPolicy is UsdLoadWithoutDescendants, then load only this prim
1418  /// and its ancestors.
1419  ///
1420  /// See UsdStage::Load for additional details.
1421  USD_API
1423 
1424  /// Unloads this prim and all its descendants.
1425  ///
1426  /// See UsdStage::Unload for additional details.
1427  USD_API
1428  void Unload() const;
1429 
1430  // --------------------------------------------------------------------- //
1431  /// \name References
1432  // --------------------------------------------------------------------- //
1433 
1434  /// Return a UsdReferences object that allows one to add, remove, or
1435  /// mutate references <em>at the currently set UsdEditTarget</em>.
1436  ///
1437  /// While the UsdReferences object has no methods for \em listing the
1438  /// currently authored references on a prim, one can use a
1439  /// UsdPrimCompositionQuery to query the reference arcs that are composed
1440  /// by this prim.
1441  ///
1442  /// \sa UsdPrimCompositionQuery::GetDirectReferences
1443  USD_API
1444  UsdReferences GetReferences() const;
1445 
1446  /// Return true if this prim has any authored references.
1447  USD_API
1448  bool HasAuthoredReferences() const;
1449 
1450  // --------------------------------------------------------------------- //
1451  /// \name Inherits
1452  // --------------------------------------------------------------------- //
1453 
1454  /// Return a UsdInherits object that allows one to add, remove, or
1455  /// mutate inherits <em>at the currently set UsdEditTarget</em>.
1456  ///
1457  /// While the UsdInherits object has no methods for \em listing the
1458  /// currently authored inherits on a prim, one can use a
1459  /// UsdPrimCompositionQuery to query the inherits arcs that are composed
1460  /// by this prim.
1461  ///
1462  /// \sa UsdPrimCompositionQuery::GetDirectInherits
1463  USD_API
1464  UsdInherits GetInherits() const;
1465 
1466  /// Return true if this prim has any authored inherits.
1467  USD_API
1468  bool HasAuthoredInherits() const;
1469 
1470  // --------------------------------------------------------------------- //
1471  /// \name Specializes
1472  // --------------------------------------------------------------------- //
1473 
1474  /// Return a UsdSpecializes object that allows one to add, remove, or
1475  /// mutate specializes <em>at the currently set UsdEditTarget</em>.
1476  ///
1477  /// While the UsdSpecializes object has no methods for \em listing the
1478  /// currently authored specializes on a prim, one can use a
1479  /// UsdPrimCompositionQuery to query the specializes arcs that are composed
1480  /// by this prim.
1481  USD_API
1483 
1484  /// Returns true if this prim has any authored specializes.
1485  USD_API
1486  bool HasAuthoredSpecializes() const;
1487 
1488  // --------------------------------------------------------------------- //
1489  /// \name Instancing
1490  /// See \ref Usd_Page_ScenegraphInstancing for more details.
1491  /// @{
1492  // --------------------------------------------------------------------- //
1493 
1494  /// Return true if this prim has been marked as instanceable.
1495  ///
1496  /// Note that this is not the same as IsInstance(). A prim may return
1497  /// true for IsInstanceable() and false for IsInstance() if this prim
1498  /// is not active or if it is marked as instanceable but contains no
1499  /// instanceable data.
1500  bool IsInstanceable() const {
1501  bool instanceable = false;
1502  return GetMetadata(SdfFieldKeys->Instanceable, &instanceable) &&
1503  instanceable;
1504  }
1505 
1506  /// Author 'instanceable' metadata for this prim at the current
1507  /// EditTarget.
1508  bool SetInstanceable(bool instanceable) const {
1509  return SetMetadata(SdfFieldKeys->Instanceable, instanceable);
1510  }
1511 
1512  /// Remove the authored 'instanceable' opinion at the current EditTarget.
1513  /// Do nothing if there is no authored opinion.
1514  bool ClearInstanceable() const {
1515  return ClearMetadata(SdfFieldKeys->Instanceable);
1516  }
1517 
1518  /// Return true if this prim has an authored opinion for 'instanceable',
1519  /// false otherwise.
1521  return HasAuthoredMetadata(SdfFieldKeys->Instanceable);
1522  }
1523 
1524  /// Return true if this prim is an instance of a prototype, false
1525  /// otherwise.
1526  ///
1527  /// If this prim is an instance, calling GetPrototype() will return
1528  /// the UsdPrim for the corresponding prototype prim.
1529  bool IsInstance() const { return _Prim()->IsInstance(); }
1530 
1531  /// Return true if this prim is an instance proxy, false otherwise.
1532  /// An instance proxy prim represents a descendent of an instance
1533  /// prim.
1534  bool IsInstanceProxy() const {
1536  }
1537 
1538  /// Return true if the given \p path identifies a prototype prim,
1539  /// false otherwise.
1540  ///
1541  /// This function will return false for prim and property paths
1542  /// that are descendants of a prototype prim path.
1543  ///
1544  /// \sa IsPathInPrototype
1545  USD_API
1546  static bool IsPrototypePath(const SdfPath& path);
1547 
1548  /// Return true if the given \p path identifies a prototype prim or
1549  /// a prim or property descendant of a prototype prim, false otherwise.
1550  ///
1551  /// \sa IsPrototypePath
1552  USD_API
1553  static bool IsPathInPrototype(const SdfPath& path);
1554 
1555  /// Return true if this prim is an instancing prototype prim,
1556  /// false otherwise.
1557  ///
1558  /// \sa IsInPrototype
1559  bool IsPrototype() const { return _Prim()->IsPrototype(); }
1560 
1561  /// Return true if this prim is a prototype prim or a descendant
1562  /// of a prototype prim, false otherwise.
1563  ///
1564  /// \sa IsPrototype
1565  bool IsInPrototype() const {
1566  return (IsInstanceProxy() ?
1568  }
1569 
1570  /// If this prim is an instance, return the UsdPrim for the corresponding
1571  /// prototype. Otherwise, return an invalid UsdPrim.
1572  USD_API
1573  UsdPrim GetPrototype() const;
1574 
1575  /// If this prim is an instance proxy, return the UsdPrim for the
1576  /// corresponding prim in the instance's prototype. Otherwise, return an
1577  /// invalid UsdPrim.
1579  if (IsInstanceProxy()) {
1580  return UsdPrim(_Prim(), SdfPath());
1581  }
1582  return UsdPrim();
1583  }
1584 
1585  /// If this prim is a prototype prim, returns all prims that are instances
1586  /// of this prototype. Otherwise, returns an empty vector.
1587  ///
1588  /// Note that this function will return prims in prototypes for instances
1589  /// that are nested beneath other instances.
1590  USD_API
1591  std::vector<UsdPrim> GetInstances() const;
1592  /// @}
1593 
1594  // --------------------------------------------------------------------- //
1595  /// \name Composition Structure
1596  /// @{
1597  // --------------------------------------------------------------------- //
1598 
1599  /// Return the cached prim index containing all sites that can contribute
1600  /// opinions to this prim.
1601  ///
1602  /// The prim index can be used to examine the composition arcs and scene
1603  /// description sites that can contribute to this prim's property and
1604  /// metadata values.
1605  ///
1606  /// The prim index returned by this function is optimized and may not
1607  /// include sites that do not contribute opinions to this prim. Use
1608  /// UsdPrim::ComputeExpandedPrimIndex to compute a prim index that includes
1609  /// all possible sites that could contribute opinions.
1610  ///
1611  /// This prim index will be empty for prototype prims. This ensures that
1612  /// these prims do not provide any attribute or metadata values. For all
1613  /// other prims in prototypes, this is the prim index that was chosen to
1614  /// be shared with all other instances. In either case, the prim index's
1615  /// path will not be the same as the prim's path.
1616  ///
1617  /// Prim indexes may be invalidated by changes to the UsdStage and cannot
1618  /// detect if they are expired. Clients should avoid keeping copies of the
1619  /// prim index across such changes, which include scene description
1620  /// changes or changes to load state.
1621  const PcpPrimIndex &GetPrimIndex() const { return _Prim()->GetPrimIndex(); }
1622 
1623  /// Compute the prim index containing all sites that could contribute
1624  /// opinions to this prim.
1625  ///
1626  /// This function is similar to UsdPrim::GetPrimIndex. However, the
1627  /// returned prim index includes all sites that could possibly contribute
1628  /// opinions to this prim, not just the sites that currently do so. This is
1629  /// useful in certain situations; for example, this could be used to
1630  /// generate a list of sites where clients could make edits to affect this
1631  /// prim, or for debugging purposes.
1632  ///
1633  /// This function may be relatively slow, since it will recompute the prim
1634  /// index on every call. Clients should prefer UsdPrim::GetPrimIndex unless
1635  /// the additional site information is truly needed.
1636  USD_API
1638 
1639  /// @}
1640 
1641 private:
1642  friend class UsdObject;
1645  friend class UsdProperty;
1646  friend class UsdSchemaBase;
1647  friend class UsdAPISchemaBase;
1648  friend class UsdStage;
1649  friend class UsdPrimRange;
1650  friend class Usd_PrimData;
1654 
1655  // Prim constructor.
1656  UsdPrim(const Usd_PrimDataHandle &primData,
1657  const SdfPath &proxyPrimPath)
1658  : UsdObject(primData, proxyPrimPath) { }
1659 
1660  // General constructor.
1661  UsdPrim(UsdObjType objType,
1662  const Usd_PrimDataHandle &prim,
1663  const SdfPath &proxyPrimPath,
1664  const TfToken &propName)
1665  : UsdObject(objType, prim, proxyPrimPath, propName) {}
1666 
1667  // Helper to make a sibling range.
1668  inline SiblingRange
1669  _MakeSiblingRange(const Usd_PrimFlagsPredicate &pred) const;
1670 
1671  // Helper to make a range of descendants.
1672  inline SubtreeRange
1673  _MakeDescendantsRange(const Usd_PrimFlagsPredicate &pred) const;
1674 
1675  // Helper to make a vector of properties from names.
1676  std::vector<UsdProperty>
1677  _MakeProperties(const TfTokenVector &names) const;
1678 
1679  // Helper for Get{Authored}{PropertyNames,Properties}
1680  TfTokenVector _GetPropertyNames(
1681  bool onlyAuthored,
1682  bool applyOrder=true,
1683  const PropertyPredicateFunc &predicate={}) const;
1684 
1685  // Helper for Get(Authored)PropertiesInNamespace.
1686  std::vector<UsdProperty>
1687  _GetPropertiesInNamespace(const std::string &namespaces,
1688  bool onlyAuthored) const;
1689 
1690  // Helper for Get(Authored)Attributes.
1691  std::vector<UsdAttribute>
1692  _GetAttributes(bool onlyAuthored, bool applyOrder=false) const;
1693 
1694  // Helper for Get(Authored)Relationships.
1695  std::vector<UsdRelationship>
1696  _GetRelationships(bool onlyAuthored, bool applyOrder=false) const;
1697 
1698  friend const PcpPrimIndex &Usd_PrimGetSourcePrimIndex(const UsdPrim&);
1699  // Return a const reference to the source PcpPrimIndex for this prim.
1700  //
1701  // For all prims in prototypes (which includes the prototype prim itself),
1702  // this is the prim index for the instance that was chosen to serve
1703  // as the prototype for all other instances. This prim index will not
1704  // have the same path as the prim's path.
1705  //
1706  // This is a private helper but is also wrapped out to Python
1707  // for testing and debugging purposes.
1708  const PcpPrimIndex &_GetSourcePrimIndex() const
1709  { return _Prim()->GetSourcePrimIndex(); }
1710 };
1711 
1712 #ifdef doxygen
1713 
1714 /// Forward traversal iterator of sibling ::UsdPrim s. This is a
1715 /// standard-compliant iterator that may be used with STL algorithms, etc.
1716 class UsdPrimSiblingIterator {
1717 public:
1718  /// Iterator value type.
1719  typedef UsdPrim value_type;
1720  /// Iterator reference type, in this case the same as \a value_type.
1721  typedef value_type reference;
1722  /// Iterator difference type.
1723  typedef unspecified-integral-type difference_type;
1724  /// Dereference.
1725  reference operator*() const;
1726  /// Indirection.
1727  unspecified-type operator->() const;
1728  /// Postincrement.
1729  UsdPrimSiblingIterator &operator++();
1730  /// Preincrement.
1731  UsdPrimSiblingIterator operator++(int);
1732 private:
1733  /// Equality.
1734  friend bool operator==(const UsdPrimSiblingIterator &lhs,
1735  const UsdPrimSiblingIterator &rhs);
1736  /// Inequality.
1737  friend bool operator!=(const UsdPrimSiblingIterator &lhs,
1738  const UsdPrimSiblingIterator &rhs);
1739 };
1740 
1741 /// Forward iterator range of sibling ::UsdPrim s. This range type contains a
1742 /// pair of UsdPrimSiblingIterator s, denoting a half-open range of UsdPrim
1743 /// siblings. It provides a subset of container-like API, such as begin(),
1744 /// end(), front(), empty(), etc.
1745 class UsdPrimSiblingRange {
1746 public:
1747  /// Iterator type.
1748  typedef UsdPrimSiblingIterator iterator;
1749  /// Const iterator type.
1750  typedef UsdPrimSiblingIterator const_iterator;
1751  /// Iterator difference type.
1752  typedef unspecified-integral-type difference_type;
1753  /// Iterator value_type.
1755  /// Iterator reference_type.
1757 
1758  /// Construct with a pair of iterators.
1761 
1762  /// Construct/convert from another compatible range type.
1763  template <class ForwardRange>
1764  UsdPrimSiblingRange(const ForwardRange &r);
1765 
1766  /// Assign from another compatible range type.
1767  template <class ForwardRange>
1768  UsdPrimSiblingRange &operator=(const ForwardRange &r);
1769 
1770  /// First iterator.
1771  iterator begin() const;
1772 
1773  /// Past-the-end iterator.
1774  iterator end() const;
1775 
1776  /// Return !empty().
1777  operator unspecified_bool_type() const;
1778 
1779  /// Equality compare.
1780  bool equal(const iterator_range&) const;
1781 
1782  /// Return *begin(). This range must not be empty.
1783  reference front() const;
1784 
1785  /// Advance this range's begin iterator.
1786  iterator_range& advance_begin(difference_type n);
1787 
1788  /// Advance this range's end iterator.
1789  iterator_range& advance_end(difference_type n);
1790 
1791  ; /// Return begin() == end().
1792  bool empty() const;
1793 
1794 private:
1795  /// Equality comparison.
1796  friend bool operator==(const UsdPrimSiblingRange &lhs,
1797  const UsdPrimSiblingRange &rhs);
1798  /// Inequality comparison.
1799  friend bool operator!=(const UsdPrimSiblingRange &lhs,
1800  const UsdPrimSiblingRange &rhs);
1801 };
1802 
1803 #else
1804 
1805 // Sibling iterator class. Converts ref to weak and filters according to a
1806 // supplied predicate.
1807 class UsdPrimSiblingIterator : public hboost::iterator_adaptor<
1808  UsdPrimSiblingIterator, // crtp base.
1809  const Usd_PrimData *, // base iterator.
1810  UsdPrim, // value type.
1811  hboost::forward_traversal_tag, // traversal
1812  UsdPrim> // reference type.
1813 {
1814 public:
1815  // Default ctor.
1817 
1818 private:
1819  friend class UsdPrim;
1820 
1821  // Constructor used by Prim.
1822  UsdPrimSiblingIterator(const base_type &i, const SdfPath& proxyPrimPath,
1823  const Usd_PrimFlagsPredicate &predicate)
1824  : iterator_adaptor_(i)
1825  , _proxyPrimPath(proxyPrimPath)
1826  , _predicate(predicate) {
1827  // Need to advance iterator to first matching element.
1828  if (base() && !Usd_EvalPredicate(_predicate, base(), _proxyPrimPath))
1829  increment();
1830  }
1831 
1832  // Core implementation invoked by iterator_adaptor.
1834  bool equal(const UsdPrimSiblingIterator &other) const {
1835  return base() == other.base() &&
1836  _proxyPrimPath == other._proxyPrimPath &&
1837  _predicate == other._predicate;
1838  }
1839 
1840  void increment() {
1841  base_type &base = base_reference();
1842  if (Usd_MoveToNextSiblingOrParent(base, _proxyPrimPath, _predicate)) {
1843  base = nullptr;
1844  _proxyPrimPath = SdfPath();
1845  }
1846  }
1847 
1848  reference dereference() const {
1849  return UsdPrim(base(), _proxyPrimPath);
1850  }
1851 
1852  SdfPath _proxyPrimPath;
1853  Usd_PrimFlagsPredicate _predicate;
1854 };
1855 
1856 // Typedef iterator range.
1857 typedef hboost::iterator_range<UsdPrimSiblingIterator> UsdPrimSiblingRange;
1858 
1859 // Inform TfIterator it should feel free to make copies of the range type.
1860 template <>
1862  UsdPrimSiblingRange> : hboost::true_type {};
1863 template <>
1865  const UsdPrimSiblingRange> : hboost::true_type {};
1866 
1867 #endif // doxygen
1868 
1869 
1870 UsdPrimSiblingRange
1872 {
1873  return _MakeSiblingRange(
1875 }
1876 
1877 UsdPrimSiblingRange
1879 {
1881 }
1882 
1883 UsdPrimSiblingRange
1885 {
1887 }
1888 
1889 // Helper to make a sibling range.
1891 UsdPrim::_MakeSiblingRange(const Usd_PrimFlagsPredicate &pred) const {
1892  Usd_PrimDataConstPtr firstChild = get_pointer(_Prim());
1893  SdfPath firstChildPath = _ProxyPrimPath();
1894  if (!Usd_MoveToChild(firstChild, firstChildPath, pred)) {
1895  firstChild = nullptr;
1896  firstChildPath = SdfPath();
1897  }
1898 
1899  return SiblingRange(
1900  SiblingIterator(firstChild, firstChildPath, pred),
1901  SiblingIterator(nullptr, SdfPath(), pred));
1902 }
1903 
1904 #ifdef doxygen
1905 
1906 /// Forward traversal iterator of sibling ::UsdPrim s. This is a
1907 /// standard-compliant iterator that may be used with STL algorithms, etc.
1908 class UsdPrimSubtreeIterator {
1909 public:
1910  /// Iterator value type.
1911  typedef UsdPrim value_type;
1912  /// Iterator reference type, in this case the same as \a value_type.
1913  typedef value_type reference;
1914  /// Iterator difference type.
1915  typedef unspecified-integral-type difference_type;
1916  /// Dereference.
1917  reference operator*() const;
1918  /// Indirection.
1919  unspecified-type operator->() const;
1920  /// Postincrement.
1921  UsdPrimSubtreeIterator &operator++();
1922  /// Preincrement.
1923  UsdPrimSubtreeIterator operator++(int);
1924 private:
1925  /// Equality.
1926  friend bool operator==(const UsdPrimSubtreeIterator &lhs,
1927  const UsdPrimSubtreeIterator &rhs);
1928  /// Inequality.
1929  friend bool operator!=(const UsdPrimSubtreeIterator &lhs,
1930  const UsdPrimSubtreeIterator &rhs);
1931 };
1932 
1933 /// Forward iterator range of sibling ::UsdPrim s. This range type contains a
1934 /// pair of UsdPrimSubtreeIterator s, denoting a half-open range of UsdPrim
1935 /// siblings. It provides a subset of container-like API, such as begin(),
1936 /// end(), front(), empty(), etc.
1937 class UsdPrimSubtreeRange {
1938 public:
1939  /// Iterator type.
1940  typedef UsdPrimSubtreeIterator iterator;
1941  /// Const iterator type.
1942  typedef UsdPrimSubtreeIterator const_iterator;
1943  /// Iterator difference type.
1944  typedef unspecified-integral-type difference_type;
1945  /// Iterator value_type.
1947  /// Iterator reference_type.
1949 
1950  /// Construct with a pair of iterators.
1953 
1954  /// Construct/convert from another compatible range type.
1955  template <class ForwardRange>
1956  UsdPrimSubtreeRange(const ForwardRange &r);
1957 
1958  /// Assign from another compatible range type.
1959  template <class ForwardRange>
1960  UsdPrimSubtreeRange &operator=(const ForwardRange &r);
1961 
1962  /// First iterator.
1963  iterator begin() const;
1964 
1965  /// Past-the-end iterator.
1966  iterator end() const;
1967 
1968  /// Return !empty().
1969  operator unspecified_bool_type() const;
1970 
1971  /// Equality compare.
1972  bool equal(const iterator_range&) const;
1973 
1974  /// Return *begin(). This range must not be empty.
1975  reference front() const;
1976 
1977  /// Advance this range's begin iterator.
1978  iterator_range& advance_begin(difference_type n);
1979 
1980  /// Advance this range's end iterator.
1981  iterator_range& advance_end(difference_type n);
1982 
1983  /// Return begin() == end().
1984  bool empty() const;
1985 
1986 private:
1987  /// Equality comparison.
1988  friend bool operator==(const UsdPrimSubtreeRange &lhs,
1989  const UsdPrimSubtreeRange &rhs);
1990  /// Inequality comparison.
1991  friend bool operator!=(const UsdPrimSubtreeRange &lhs,
1992  const UsdPrimSubtreeRange &rhs);
1993 };
1994 
1995 #else
1996 
1997 // Subtree iterator class. Converts ref to weak and filters according to a
1998 // supplied predicate.
1999 class UsdPrimSubtreeIterator : public hboost::iterator_adaptor<
2000  UsdPrimSubtreeIterator, // crtp base.
2001  const Usd_PrimData *, // base iterator.
2002  UsdPrim, // value type.
2003  hboost::forward_traversal_tag, // traversal
2004  UsdPrim> // reference type.
2005 {
2006 public:
2007  // Default ctor.
2009 
2010 private:
2011  friend class UsdPrim;
2012 
2013  // Constructor used by Prim.
2014  UsdPrimSubtreeIterator(const base_type &i, const SdfPath &proxyPrimPath,
2015  const Usd_PrimFlagsPredicate &predicate)
2016  : iterator_adaptor_(i)
2017  , _proxyPrimPath(proxyPrimPath)
2018  , _predicate(predicate) {
2019  // Need to advance iterator to first matching element.
2020  base_type &base = base_reference();
2021  if (base && !Usd_EvalPredicate(_predicate, base, _proxyPrimPath)) {
2022  if (Usd_MoveToNextSiblingOrParent(base, _proxyPrimPath,
2023  _predicate)) {
2024  base = nullptr;
2025  _proxyPrimPath = SdfPath();
2026  }
2027  }
2028  }
2029 
2030  // Core implementation invoked by iterator_adaptor.
2032  bool equal(const UsdPrimSubtreeIterator &other) const {
2033  return base() == other.base() &&
2034  _proxyPrimPath == other._proxyPrimPath &&
2035  _predicate == other._predicate;
2036  }
2037 
2038  void increment() {
2039  base_type &base = base_reference();
2040  if (!Usd_MoveToChild(base, _proxyPrimPath, _predicate)) {
2041  while (Usd_MoveToNextSiblingOrParent(base, _proxyPrimPath,
2042  _predicate)) {}
2043  }
2044  }
2045 
2046  reference dereference() const {
2047  return UsdPrim(base(), _proxyPrimPath);
2048  }
2049 
2050  SdfPath _proxyPrimPath;
2051  Usd_PrimFlagsPredicate _predicate;
2052 };
2053 
2054 // Typedef iterator range.
2055 typedef hboost::iterator_range<UsdPrimSubtreeIterator> UsdPrimSubtreeRange;
2056 
2057 // Inform TfIterator it should feel free to make copies of the range type.
2058 template <>
2060  UsdPrimSubtreeRange> : hboost::true_type {};
2061 template <>
2063  const UsdPrimSubtreeRange> : hboost::true_type {};
2064 
2065 #endif // doxygen
2066 
2067 UsdPrimSubtreeRange
2069 {
2070  return _MakeDescendantsRange(
2072 }
2073 
2074 UsdPrimSubtreeRange
2076 {
2078 }
2079 
2080 UsdPrimSubtreeRange
2082 {
2084 }
2085 
2086 // Helper to make a sibling range.
2088 UsdPrim::_MakeDescendantsRange(const Usd_PrimFlagsPredicate &pred) const {
2089  Usd_PrimDataConstPtr firstChild = get_pointer(_Prim());
2090  SdfPath firstChildPath = _ProxyPrimPath();
2091  Usd_PrimDataConstPtr endChild = firstChild;
2092  SdfPath endChildPath = firstChildPath;
2093  if (Usd_MoveToChild(firstChild, firstChildPath, pred)) {
2094  while (Usd_MoveToNextSiblingOrParent(endChild, endChildPath, pred)) {}
2095  }
2096 
2097  return SubtreeRange(
2098  SubtreeIterator(firstChild, firstChildPath, pred),
2099  SubtreeIterator(endChild, endChildPath, pred));
2100 }
2101 
2102 
2103 ////////////////////////////////////////////////////////////////////////
2104 // UsdObject methods that require UsdPrim be a complete type.
2105 
2106 inline UsdPrim
2108 {
2109  return UsdPrim(_prim, _proxyPrimPath);
2110 }
2111 
2113 
2114 #endif // PXR_USD_USD_PRIM_H
2115 
USD_API SdfPrimSpecHandleVector GetPrimStack() const
void Usd_MoveToParent(PrimDataPtr &p, SdfPath &proxyPrimPath)
Definition: primData.h:515
friend class UsdPrim
Definition: prim.h:1819
USD_API SdfPathVector FindAllRelationshipTargetPaths(std::function< bool(UsdRelationship const &)> const &pred=nullptr, bool recurseOnTargets=false) const
Color4< T > operator*(S a, const Color4< T > &v)
Definition: ImathColor.h:728
UsdObjType
Definition: object.h:49
GLuint GLdouble GLdouble GLint GLint order
Definition: glew.h:3460
Usd_PrimFlagsPredicate Usd_CreatePredicateForTraversal(const PrimDataPtr &p, const SdfPath &proxyPrimPath, Usd_PrimFlagsPredicate pred)
Definition: primData.h:495
#define USD_API
Definition: api.h:40
GLenum GLuint GLint GLint layer
Definition: glcorearb.h:1298
friend class hboost::iterator_core_access
Definition: prim.h:2031
hboost::math::policies::policy< hboost::math::policies::domain_error< hboost::math::policies::ignore_error >, hboost::math::policies::pole_error< hboost::math::policies::ignore_error >, hboost::math::policies::overflow_error< hboost::math::policies::ignore_error >, hboost::math::policies::underflow_error< hboost::math::policies::ignore_error >, hboost::math::policies::denorm_error< hboost::math::policies::ignore_error >, hboost::math::policies::rounding_error< hboost::math::policies::ignore_error >, hboost::math::policies::evaluation_error< hboost::math::policies::ignore_error >, hboost::math::policies::indeterminate_result_error< hboost::math::policies::ignore_error > > policy
Definition: SYS_MathCbrt.h:35
USD_API bool HasAuthoredPayloads() const
Return true if this prim has any authored payloads.
UsdPrim GetPrimInPrototype() const
Definition: prim.h:1578
USD_API UsdVariantSet GetVariantSet(const std::string &variantSetName) const
USD_API std::vector< UsdAttribute > GetAuthoredAttributes() const
bool CanApplyAPI(std::string *whyNot=nullptr) const
Definition: prim.h:624
SiblingRange GetChildren() const
Definition: prim.h:1884
USD_API bool HasAuthoredInherits() const
Return true if this prim has any authored inherits.
USD_API bool HasAuthoredMetadata(const TfToken &key) const
SdfSpecifier GetSpecifier() const
Return this prim's composed specifier.
Definition: prim.h:166
static TF_API std::string GetCanonicalTypeName(const std::type_info &)
bool HasAuthoredInstanceable() const
Definition: prim.h:1520
UsdPrimSiblingRange SiblingRange
Definition: prim.h:137
void ClearPropertyOrder() const
Definition: prim.h:437
GLsizei const GLchar *const * path
Definition: glcorearb.h:3340
USD_API UsdRelationship CreateRelationship(const TfToken &relName, bool custom=true) const
#define TF_CODING_ERROR
GLenum const void GLuint GLint reference
Definition: glew.h:13927
static USD_API bool IsPathInPrototype(const SdfPath &path)
SiblingRange GetAllChildren() const
Return all this prim's children as an iterable range.
Definition: prim.h:1878
const UsdPrimTypeInfo & GetPrimTypeInfo() const
Definition: prim.h:154
USD_API UsdAttribute CreateAttribute(const TfToken &name, const SdfValueTypeName &typeName, bool custom, SdfVariability variability=SdfVariabilityVarying) const
bool IsInstanceProxy() const
Definition: prim.h:1534
SubtreeRange GetAllDescendants() const
Definition: prim.h:2075
USD_API TfTokenVector GetAllChildrenNames() const
USD_API bool HasAuthoredReferences() const
Return true if this prim has any authored references.
void ClearChildrenReorder() const
Definition: prim.h:1027
const UsdPrimDefinition & GetPrimDefinition() const
Definition: prim.h:161
USD_API UsdProperty GetPropertyAtPath(const SdfPath &path) const
Load a prim plus all its descendants.
Definition: common.h:118
USD_API UsdPrim GetPrimAtPath(const SdfPath &path) const
bool SetMetadata(const TfToken &key, const T &value) const
Definition: object.h:731
GLuint const GLchar * name
Definition: glcorearb.h:785
USD_API bool HasProperty(const TfToken &propName) const
USD_API void Load(UsdLoadPolicy policy=UsdLoadWithDescendants) const
USD_API bool RemoveProperty(const TfToken &propName)
bool GetMetadata(const TfToken &key, T *value) const
Definition: object.h:723
USD_API bool ClearMetadata(const TfToken &key) const
uint64 value_type
Definition: GA_PrimCompat.h:29
USD_API bool RemoveAppliedSchema(const TfToken &appliedSchemaName) const
USD_API std::vector< UsdProperty > GetAuthoredProperties(const PropertyPredicateFunc &predicate={}) const
Y * get_pointer(TfWeakPtrFacade< X, Y > const &p)
Definition: weakPtrFacade.h:86
USD_API UsdPrim GetPrototype() const
bool IsDefined() const
Definition: prim.h:265
bool HasAPI(const TfToken &instanceName=TfToken()) const
Definition: prim.h:577
USD_API TfTokenVector GetPropertyNames(const PropertyPredicateFunc &predicate={}) const
USD_API std::vector< UsdProperty > GetProperties(const PropertyPredicateFunc &predicate={}) const
friend struct UsdPrim_AttrConnectionFinder
Definition: prim.h:1653
bool IsLoaded() const
Definition: prim.h:249
bool IsActive() const
Definition: prim.h:219
USD_API bool ClearPayload() const
bool IsA() const
Definition: prim.h:526
USD_API SdfPathVector FindAllAttributeConnectionPaths(std::function< bool(UsdAttribute const &)> const &pred=nullptr, bool recurseOnSources=false) const
bool operator==(const BaseDimensions< T > &a, const BaseDimensions< Y > &b)
Definition: Dimensions.h:137
Single Apply API schema.
bool RemoveAPI(const TfToken &instanceName) const
Definition: prim.h:823
Definition: token.h:87
USD_API UsdProperty GetProperty(const TfToken &propName) const
GLint GLint GLsizei GLint GLenum GLenum type
Definition: glcorearb.h:107
bool IsGroup() const
Definition: prim.h:258
USD_API bool HasAttribute(const TfToken &attrName) const
USD_API bool HasRelationship(const TfToken &relName) const
USD_API void Unload() const
USD_API TfTokenVector GetFilteredChildrenNames(const Usd_PrimFlagsPredicate &predicate) const
bool Usd_IsInstanceProxy(const PrimDataPtr &p, const SdfPath &proxyPrimPath)
Definition: primData.h:481
USD_API bool HasAuthoredSpecializes() const
Returns true if this prim has any authored specializes.
GLuint GLuint end
Definition: glcorearb.h:474
GLsizei const GLchar *const * string
Definition: glcorearb.h:813
USD_API UsdReferences GetReferences() const
friend class hboost::iterator_core_access
Definition: prim.h:1833
const SdfPath & GetPrimPath() const
Definition: object.h:209
bool SetInstanceable(bool instanceable) const
Definition: prim.h:1508
USD_API UsdAttribute GetAttributeAtPath(const SdfPath &path) const
bool HasAuthoredActive() const
Definition: prim.h:242
static USD_API bool IsPrototypePath(const SdfPath &path)
void SetPropertyOrder(const TfTokenVector &order) const
Definition: prim.h:431
USD_API bool AddAppliedSchema(const TfToken &appliedSchemaName) const
USD_API bool SetPayload(const SdfPayload &payload) const
Definition: prim.h:132
bool ApplyAPI(const TfToken &instanceName) const
Definition: prim.h:742
std::function< bool(const TfToken &propertyName)> PropertyPredicateFunc
Definition: prim.h:285
SdfSpecifier
Definition: types.h:123
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:442
GLuint const GLuint * names
Definition: glew.h:2695
friend struct UsdPrim_RelTargetFinder
Definition: prim.h:1652
hboost::iterator_range< UsdPrimSubtreeIterator > UsdPrimSubtreeRange
Definition: prim.h:75
const SdfPath & _ProxyPrimPath() const
Definition: object.h:701
bool IsAbstract() const
Return true if this prim or any of its ancestors is a class.
Definition: prim.h:261
Definition: path.h:288
bool IsPrototype() const
Definition: prim.h:1559
USD_API PcpPrimIndex ComputeExpandedPrimIndex() const
bool HasAuthoredTypeName() const
Return true if a typeName has been authored.
Definition: prim.h:211
USD_API UsdRelationship GetRelationshipAtPath(const SdfPath &path) const
bool ClearInstanceable() const
Definition: prim.h:1514
USD_API TfTokenVector GetAppliedSchemas() const
void SetChildrenReorder(const TfTokenVector &order) const
Definition: prim.h:1021
UsdPrim GetParent() const
Definition: prim.h:1038
USD_API UsdPayloads GetPayloads() const
bool ClearTypeName() const
Definition: prim.h:206
std::vector< class SdfPath > SdfPathVector
A vector of SdfPaths.
Definition: path.h:209
bool Usd_MoveToChild(PrimDataPtr &p, SdfPath &proxyPrimPath, PrimDataPtr end, const Usd_PrimFlagsPredicate &pred)
Definition: primData.h:602
USD_API TfTokenVector GetAuthoredPropertyNames(const PropertyPredicateFunc &predicate={}) const
USD_API UsdInherits GetInherits() const
bool RemoveAPI() const
Definition: prim.h:780
USD_API UsdPrim GetNextSibling() const
GLdouble n
Definition: glcorearb.h:2007
SdfVariability
Definition: types.h:179
USD_API UsdVariantSets GetVariantSets() const
friend class UsdPrim
Definition: prim.h:2011
const Usd_PrimDataHandle & _Prim() const
Definition: object.h:695
UsdPrim GetPrim() const
Definition: prim.h:2107
SubtreeRange GetDescendants() const
Definition: prim.h:2081
USD_API std::vector< UsdRelationship > GetRelationships() const
Like GetProperties(), but exclude all attributes from the result.
bool IsInstance() const
Definition: prim.h:1529
SubtreeRange GetFilteredDescendants(const Usd_PrimFlagsPredicate &predicate) const
Definition: prim.h:2068
UsdLoadPolicy
Definition: common.h:116
USD_API const Usd_PrimFlagsConjunction UsdPrimDefaultPredicate
Multiple Apply API Schema.
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1375
bool ClearActive() const
Definition: prim.h:234
hboost::iterator_range< UsdPrimSiblingIterator > UsdPrimSiblingRange
Definition: prim.h:72
bool ApplyAPI() const
Definition: prim.h:700
USD_API const Usd_PrimFlagsPredicate UsdPrimAllPrimsPredicate
bool Usd_MoveToNextSiblingOrParent(PrimDataPtr &p, SdfPath &proxyPrimPath, PrimDataPtr end, const Usd_PrimFlagsPredicate &pred)
Definition: primData.h:545
const PcpPrimIndex & GetPrimIndex() const
Definition: prim.h:1621
USD_API std::vector< UsdProperty > GetAuthoredPropertiesInNamespace(const std::vector< std::string > &namespaces) const
bool IsModel() const
Definition: prim.h:253
USD_API TfTokenVector GetPropertyOrder() const
Return the strongest propertyOrder metadata value authored on this prim.
bool IsInstanceable() const
Definition: prim.h:1500
UsdPrimSubtreeIterator SubtreeIterator
Convenience typedefs.
Definition: prim.h:140
USD_API UsdObject GetObjectAtPath(const SdfPath &path) const
USD_API std::vector< UsdRelationship > GetAuthoredRelationships() const
USD_API TfTokenVector GetChildrenNames() const
USD_API UsdSpecializes GetSpecializes() const
const TfToken & GetTypeName() const
Definition: prim.h:197
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USD_API TfTokenVector GetChildrenReorder() const
USD_API UsdRelationship GetRelationship(const TfToken &relName) const
GLsizei const GLfloat * value
Definition: glcorearb.h:823
bool equal(T1 a, T2 b, T3 t)
Definition: ImathFun.h:143
Definition: type.h:64
USD_API UsdPrim GetChild(const TfToken &name) const
USD_API bool HasVariantSets() const
bool CanApplyAPI(const TfToken &instanceName, std::string *whyNot=nullptr) const
Definition: prim.h:660
USD_API std::vector< UsdAttribute > GetAttributes() const
Like GetProperties(), but exclude all relationships from the result.
USD_API std::vector< UsdPrim > GetInstances() const
bool SetTypeName(const TfToken &typeName) const
Author this Prim's typeName at the current EditTarget.
Definition: prim.h:200
bool operator!=(const BaseDimensions< T > &a, const BaseDimensions< Y > &b)
Definition: Dimensions.h:165
#define const
Definition: zconf.h:214
bool SetSpecifier(SdfSpecifier specifier) const
Definition: prim.h:186
USD_API UsdPrim GetFilteredNextSibling(const Usd_PrimFlagsPredicate &predicate) const
GLboolean r
Definition: glcorearb.h:1221
UsdPrim()
Construct an invalid prim.
Definition: prim.h:144
bool SetActive(bool active) const
Definition: prim.h:225
USD_API UsdAttribute GetAttribute(const TfToken &attrName) const
bool HasDefiningSpecifier() const
Definition: prim.h:269
USD_API std::vector< UsdProperty > GetPropertiesInNamespace(const std::vector< std::string > &namespaces) const
UsdPrimSubtreeRange SubtreeRange
Definition: prim.h:141
USD_API bool HasPayload() const
UsdPrimSiblingIterator SiblingIterator
Convenience typedefs.
Definition: prim.h:136
bool IsInPrototype() const
Definition: prim.h:1565
SiblingRange GetFilteredChildren(const Usd_PrimFlagsPredicate &predicate) const
Definition: prim.h:1871
friend const PcpPrimIndex & Usd_PrimGetSourcePrimIndex(const UsdPrim &)
USD_API bool IsPseudoRoot() const