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  USD_API
432  void SetPropertyOrder(const TfTokenVector &order) const;
433 
434  /// Remove all scene description for the property with the
435  /// given \p propName <em>in the current UsdEditTarget</em>.
436  /// Return true if the property is removed, false otherwise.
437  ///
438  /// Because this method can only remove opinions about the property from
439  /// the current EditTarget, you may generally find it more useful to use
440  /// UsdAttribute::Block(), which will ensure that all values from the
441  /// EditTarget and weaker layers for the property will be ignored.
442  USD_API
443  bool RemoveProperty(const TfToken &propName);
444 
445  /// Return a UsdProperty with the name \a propName. The property
446  /// returned may or may not \b actually exist so it must be checked for
447  /// validity. Suggested use:
448  ///
449  /// \code
450  /// if (UsdProperty myProp = prim.GetProperty("myProp")) {
451  /// // myProp is safe to use.
452  /// // Edits to the owning stage requires subsequent validation.
453  /// } else {
454  /// // myProp was not defined/authored
455  /// }
456  /// \endcode
457  USD_API
458  UsdProperty GetProperty(const TfToken &propName) const;
459 
460  /// Return true if this prim has an property named \p propName, false
461  /// otherwise.
462  USD_API
463  bool HasProperty(const TfToken &propName) const;
464 
465 private:
466  // The non-templated implementation of UsdPrim::IsA using the
467  // TfType system. \p validateSchemaType is provided for python clients
468  // because they can't use compile time assertions on the input type.
469  USD_API
470  bool _IsA(const TfType& schemaType, bool validateSchemaType) const;
471 
472  // The non-templated implementation of UsdPrim::HasAPI using the
473  // TfType system.
474  //
475  // \p validateSchemaType is provided for python clients
476  // because they can't use compile time assertions on the input type.
477  //
478  // \p instanceName is used to determine whether a particular instance
479  // of a multiple-apply API schema has been applied to the prim.
480  USD_API
481  bool _HasAPI(const TfType& schemaType, bool validateSchemaType,
482  const TfToken &instanceName) const;
483 
484  // Private implementation for all ApplyAPI methods. This does no input
485  // validation as the public methods are expected to have already done either
486  // compile time or runtime validation already.
487  USD_API
488  bool _ApplyAPI(const TfType& schemaType,
489  const TfToken& instanceName = TfToken()) const;
490 
491  // Private implementation for all RemoveAPI methods. This does no input
492  // validation as the public methods are expected to have already done either
493  // compile time or runtime validation already.
494  USD_API
495  bool _RemoveAPI(const TfType& schemaType,
496  const TfToken& instanceName = TfToken()) const;
497 
498 public:
499  /// Return true if the prim's schema type, is or inherits schema type T.
500  /// \sa GetPrimTypeInfo
501  /// \sa UsdPrimTypeInfo::GetSchemaType
502  /// \sa \ref Usd_OM_FallbackPrimTypes
503  template <typename T>
504  bool IsA() const {
506  "Provided type must derive UsdSchemaBase.");
507  return _IsA(TfType::Find<T>(), /*validateSchemaType=*/false);
508  };
509 
510  /// Return true if the prim's schema type is or inherits \p schemaType.
511  /// \sa GetPrimTypeInfo
512  /// \sa UsdPrimTypeInfo::GetSchemaType
513  /// \sa \ref Usd_OM_FallbackPrimTypes
514  USD_API
515  bool IsA(const TfType& schemaType) const;
516 
517  /// Return true if the UsdPrim has had an API schema represented by the C++
518  /// class type <b>T</b> applied to it through the Apply() method provided
519  /// on the API schema class.
520  ///
521  /// \p instanceName, if non-empty is used to determine if a particular
522  /// instance of a multiple-apply API schema (eg. UsdCollectionAPI) has been
523  /// applied to the prim. A coding error is issued if a non-empty
524  /// \p instanceName is passed in and <b>T</b> represents a single-apply API
525  /// schema.
526  ///
527  /// <b>Using HasAPI in C++</b>
528  /// \code
529  /// UsdPrim prim = stage->OverridePrim("/path/to/prim");
530  /// MyDomainBozAPI = MyDomainBozAPI::Apply(prim);
531  /// assert(prim.HasAPI<MyDomainBozAPI>());
532  ///
533  /// UsdCollectionAPI collAPI = UsdCollectionAPI::Apply(prim,
534  /// /*instanceName*/ TfToken("geom"))
535  /// assert(prim.HasAPI<UsdCollectionAPI>()
536  /// assert(prim.HasAPI<UsdCollectionAPI>(/*instanceName*/ TfToken("geom")))
537  /// \endcode
538  ///
539  /// The python version of this method takes as an argument the TfType
540  /// of the API schema class. Similar validation of the schema type is
541  /// performed in python at run-time and a coding error is issued if
542  /// the given type is not a valid applied API schema.
543  ///
544  /// <b>Using HasAPI in Python</b>
545  /// \code{.py}
546  /// prim = stage.OverridePrim("/path/to/prim")
547  /// bozAPI = MyDomain.BozAPI.Apply(prim)
548  /// assert prim.HasAPI(MyDomain.BozAPI)
549  ///
550  /// collAPI = Usd.CollectionAPI.Apply(prim, "geom")
551  /// assert(prim.HasAPI(Usd.CollectionAPI))
552  /// assert(prim.HasAPI(Usd.CollectionAPI, instanceName="geom"))
553  /// \endcode
554  template <typename T>
555  bool HasAPI(const TfToken &instanceName=TfToken()) const {
557  "Provided type must derive UsdAPISchemaBase.");
559  "Provided type must not be UsdAPISchemaBase.");
560  static_assert(
561  (T::schemaType == UsdSchemaType::SingleApplyAPI
562  || T::schemaType == UsdSchemaType::MultipleApplyAPI),
563  "Provided schema type must be an applied API schema.");
564 
565  if (T::schemaType != UsdSchemaType::MultipleApplyAPI
566  && !instanceName.IsEmpty()) {
567  TF_CODING_ERROR("HasAPI: single application API schemas like %s do "
568  "not contain an application instanceName ( %s ).",
569  TfType::GetCanonicalTypeName(typeid(T)).c_str(),
570  instanceName.GetText());
571  return false;
572  }
573 
574  return _HasAPI(TfType::Find<T>(), /*validateSchemaType=*/false,
575  instanceName);
576  }
577 
578  /// Return true if a prim has an API schema with TfType \p schemaType.
579  ///
580  /// \p instanceName, if non-empty is used to determine if a particular
581  /// instance of a multiple-apply API schema (eg. UsdCollectionAPI) has been
582  /// applied to the prim. A coding error is issued if a non-empty
583  /// \p instanceName is passed in and <b>T</b> represents a single-apply API
584  /// schema.
585  USD_API
586  bool HasAPI(const TfType& schemaType,
587  const TfToken& instanceName=TfToken()) const;
588 
589  /// Applies a <b>single-apply</b> API schema with the given C++ type
590  /// 'SchemaType' to this prim in the current edit target.
591  ///
592  /// This information is stored by adding the API schema's name token to the
593  /// token-valued, listOp metadata \em apiSchemas on this prim.
594  ///
595  /// Returns true upon success or if the API schema is already applied in
596  /// the current edit target.
597  ///
598  /// An error is issued and false returned for any of the following
599  /// conditions:
600  /// \li this prim is not a valid prim for editing
601  /// \li this prim is valid, but cannot be reached or overridden in the
602  /// current edit target
603  /// \li the schema name cannot be added to the apiSchemas listOp metadata
604  template <typename SchemaType>
605  bool ApplyAPI() const {
607  "Provided type must derive UsdAPISchemaBase.");
609  "Provided type must not be UsdAPISchemaBase.");
610  static_assert(SchemaType::schemaType == UsdSchemaType::SingleApplyAPI,
611  "Provided schema type must be an single apply API schema.");
612 
613  static TfType schemaType = TfType::Find<SchemaType>();
614  return _ApplyAPI(schemaType);
615  }
616 
617  /// Applies a </b>multiple-apply</b> API schema with the given C++ type
618  /// 'SchemaType' and instance name \p instanceName to this prim in the
619  /// current edit target.
620  ///
621  /// This information is stored in the token-valued, listOp metadata
622  /// \em apiSchemas on this prim. For example, if SchemaType is
623  /// 'UsdCollectionAPI' and \p instanceName is 'plasticStuff', the name
624  /// 'CollectionAPI:plasticStuff' is added to the 'apiSchemas' listOp
625  /// metadata.
626  ///
627  /// Returns true upon success or if the API schema is already applied with
628  /// this \p instanceName in the current edit target.
629  ///
630  /// An error is issued and false returned for any of the following
631  /// conditions:
632  /// \li \p instanceName is empty
633  /// \li this prim is not a valid prim for editing
634  /// \li this prim is valid, but cannot be reached or overridden in the
635  /// current edit target
636  /// \li the schema name cannot be added to the apiSchemas listOp metadata
637  template <typename SchemaType>
638  bool ApplyAPI(const TfToken &instanceName) const {
640  "Provided type must derive UsdAPISchemaBase.");
642  "Provided type must not be UsdAPISchemaBase.");
643  static_assert(SchemaType::schemaType == UsdSchemaType::MultipleApplyAPI,
644  "Provided schema type must be a multiple apply API schema.");
645 
646  if (instanceName.IsEmpty()) {
647  TF_CODING_ERROR("ApplyAPI: for mutiple apply API schema %s, a "
648  "non-empty instance name must be provided.",
649  TfType::GetCanonicalTypeName(typeid(SchemaType)).c_str());
650  return false;
651  }
652 
653  static TfType schemaType = TfType::Find<SchemaType>();
654  return _ApplyAPI(schemaType, instanceName);
655  }
656 
657  /// Applies an API schema with the given TfType \p schemaType on this prim
658  /// in the current edit target.
659  ///
660  /// The \p schemaType must be an applied API schema type. If the
661  /// \p schemaType is a multiple-apply schema, \p instanceName must
662  /// be non-empty while for single-apply schema, \p instanceName must be
663  /// empty. A error is issued and false returned if these conditions are
664  /// not met.
665  ///
666  /// This function behaves exactly like the templated ApplyAPI functions
667  /// except for the runtime schemaType validation which happens at compile
668  /// time for the templated functions. This method is provided for python
669  /// clients. Use of the templated ApplyAPI is preferred.
670  USD_API
671  bool ApplyAPI(const TfType& schemaType,
672  const TfToken& instanceName=TfToken()) const;
673 
674 
675  /// Removes a <b>single-apply</b> API schema with the given C++ type
676  /// 'SchemaType' from this prim in the current edit target.
677  ///
678  /// This is done by removing the API schema's name token from the
679  /// token-valued, listOp metadata \em apiSchemas on this prim as well as
680  /// authoring an explicit deletion of schema name from the listOp.
681  ///
682  /// Returns true upon success or if the API schema is already deleted in
683  /// the current edit target.
684  ///
685  /// An error is issued and false returned for any of the following
686  /// conditions:
687  /// \li this prim is not a valid prim for editing
688  /// \li this prim is valid, but cannot be reached or overridden in the
689  /// current edit target
690  /// \li the schema name cannot be deleted in the apiSchemas listOp metadata
691  template <typename SchemaType>
692  bool RemoveAPI() const {
694  "Provided type must derive UsdAPISchemaBase.");
696  "Provided type must not be UsdAPISchemaBase.");
697  static_assert(SchemaType::schemaType == UsdSchemaType::SingleApplyAPI,
698  "Provided schema type must be an single apply API schema.");
699 
700  static TfType schemaType = TfType::Find<SchemaType>();
701  return _RemoveAPI(schemaType);
702  }
703 
704  /// Removes a </b>multiple-apply</b> API schema with the given C++ type
705  /// 'SchemaType' and instance name \p instanceName from this prim in the
706  /// current edit target.
707  ///
708  /// This is done by removing the instanced schema name token from the
709  /// token-valued, listOp metadata \em apiSchemas on this prim as well as
710  /// authoring an explicit deletion of the name from the listOp. For example,
711  /// if SchemaType is 'UsdCollectionAPI' and \p instanceName is
712  /// 'plasticStuff', the name 'CollectionAPI:plasticStuff' is deleted
713  /// from the 'apiSchemas' listOp metadata.
714  ///
715  /// Returns true upon success or if the API schema with this \p instanceName
716  /// is already deleted in the current edit target.
717  ///
718  /// An error is issued and false returned for any of the following
719  /// conditions:
720  /// \li \p instanceName is empty
721  /// \li this prim is not a valid prim for editing
722  /// \li this prim is valid, but cannot be reached or overridden in the
723  /// current edit target
724  /// \li the schema name cannot be deleted in the apiSchemas listOp metadata
725  template <typename SchemaType>
726  bool RemoveAPI(const TfToken &instanceName) const {
728  "Provided type must derive UsdAPISchemaBase.");
730  "Provided type must not be UsdAPISchemaBase.");
731  static_assert(SchemaType::schemaType == UsdSchemaType::MultipleApplyAPI,
732  "Provided schema type must be a multiple apply API schema.");
733 
734  static TfType schemaType = TfType::Find<SchemaType>();
735  return _RemoveAPI(schemaType, instanceName);
736  }
737 
738  /// Removes an API schema with the given TfType \p schemaType from this prim
739  /// in the current edit target.
740  ///
741  /// The \p schemaType must be an applied API schema type. If the
742  /// \p schemaType is a multiple-apply schema, \p instanceName must
743  /// be non-empty while for single-apply schema, \p instanceName must be
744  /// empty. A error is issued and false returned if these conditions are
745  /// not met.
746  ///
747  /// This function behaves exactly like the templated RemoveAPI functions
748  /// except for the runtime schemaType validation which happens at compile
749  /// time for the templated functions. This method is provided for python
750  /// clients. Use of the templated RemoveAPI is preferred.
751  USD_API
752  bool RemoveAPI(const TfType& schemaType,
753  const TfToken& instanceName=TfToken()) const;
754 
755  /// Adds the applied API schema name token \p appliedSchemaName to the
756  /// \em apiSchemas metadata for this prim at the current edit target. For
757  /// multiple-apply schemas the name token should include the instance name
758  /// for the applied schema, for example 'CollectionAPI:plasticStuff'.
759  ///
760  /// The name will only be added if the \ref SdfListOp "list operation" at
761  /// the edit target does not already have this applied schema in its
762  /// explicit, prepended, or appended lists and is always added to the end
763  /// of either the prepended or explicit items.
764  ///
765  /// Returns true upon success or if the API schema is already applied in
766  /// the current edit target.
767  ///
768  /// An error is issued and false returned for any of the following
769  /// conditions:
770  /// \li this prim is not a valid prim for editing
771  /// \li this prim is valid, but cannot be reached or overridden in the
772  /// current edit target
773  /// \li the schema name cannot be added to the apiSchemas listOp metadata
774  ///
775  /// Unlike ApplyAPI this method does not require that the name token
776  /// refer to a valid API schema type. ApplyAPI is the preferred method
777  /// for applying valid API schemas.
778  USD_API
779  bool AddAppliedSchema(const TfToken &appliedSchemaName) const;
780 
781  /// Removes the applied API schema name token \p appliedSchemaName from the
782  /// \em apiSchemas metadata for this prim at the current edit target. For
783  /// multiple-apply schemas the name token should include the instance name
784  /// for the applied schema, for example 'CollectionAPI:plasticStuff'
785  ///
786  /// For an explicit \ref SdfListOp "list operation", this removes the
787  /// applied schema name from the explicit items list if it was present. For
788  /// a non-explicit \ref SdfListOp "list operation", this will remove any
789  /// occurrence of the applied schema name from the prepended and appended
790  /// item as well as adding it to the deleted items list.
791  ///
792  /// Returns true upon success or if the API schema is already deleted in
793  /// the current edit target.
794  ///
795  /// An error is issued and false returned for any of the following
796  /// conditions:
797  /// \li this prim is not a valid prim for editing
798  /// \li this prim is valid, but cannot be reached or overridden in the
799  /// current edit target
800  /// \li the schema name cannot be deleted in the apiSchemas listOp metadata
801  ///
802  /// Unlike RemoveAPI this method does not require that the name token
803  /// refer to a valid API schema type. RemoveAPI is the preferred method
804  /// for removing valid API schemas.
805  USD_API
806  bool RemoveAppliedSchema(const TfToken &appliedSchemaName) const;
807 
808  // --------------------------------------------------------------------- //
809  /// \name Prim Children
810  // --------------------------------------------------------------------- //
811 
812  /// Return this prim's direct child named \p name if it has one, otherwise
813  /// return an invalid UsdPrim. Equivalent to:
814  /// \code
815  /// prim.GetStage()->GetPrimAtPath(prim.GetPath().AppendChild(name))
816  /// \endcode
817  USD_API
818  UsdPrim GetChild(const TfToken &name) const;
819 
820  /// Return this prim's active, loaded, defined, non-abstract children as an
821  /// iterable range. Equivalent to:
822  /// \code
823  /// GetFilteredChildren(UsdPrimDefaultPredicate)
824  /// \endcode
825  ///
826  /// See \ref Usd_PrimFlags "Prim predicate flags"
827  /// and #UsdPrimDefaultPredicate for more information.
828  inline SiblingRange GetChildren() const;
829 
830  /// Return all this prim's children as an iterable range.
831  inline SiblingRange GetAllChildren() const;
832 
833  /// Return a subset of all of this prim's children filtered by \p predicate
834  /// as an iterable range. The \p predicate is generated by combining a
835  /// series of prim flag terms with either && or || and !.
836  ///
837  /// Example usage:
838  /// \code
839  /// // Get all active model children.
840  /// GetFilteredChildren(UsdPrimIsActive && UsdPrimIsModel);
841  ///
842  /// // Get all model children that pass the default predicate.
843  /// GetFilteredChildren(UsdPrimDefaultPredicate && UsdPrimIsModel);
844  /// \endcode
845  ///
846  /// If this prim is an instance, no children will be returned unless
847  /// #UsdTraverseInstanceProxies is used to allow instance proxies to be
848  /// returned, or if this prim is itself an instance proxy.
849  ///
850  /// See \ref Usd_PrimFlags "Prim predicate flags"
851  /// and #UsdPrimDefaultPredicate for more information.
852  inline SiblingRange
853  GetFilteredChildren(const Usd_PrimFlagsPredicate &predicate) const;
854 
855  /// Return this prim's active, loaded, defined, non-abstract descendants as
856  /// an iterable range. Equivalent to:
857  /// \code
858  /// GetFilteredDescendants(UsdPrimDefaultPredicate)
859  /// \endcode
860  ///
861  /// \note This method is not yet available in python, pending some
862  /// refactoring to make it more feasible.
863  ///
864  /// See \ref Usd_PrimFlags "Prim predicate flags" and
865  /// #UsdPrimDefaultPredicate for more information, UsdStage::Traverse(),
866  /// and \c UsdPrimRange for more general Stage traversal behaviors.
867  inline SubtreeRange GetDescendants() const;
868 
869  /// Return all this prim's descendants as an iterable range.
870  ///
871  /// \note This method is not yet available in python, pending some
872  /// refactoring to make it more feasible.
873  ///
874  /// See \ref Usd_PrimFlags "Prim predicate flags" and
875  /// #UsdPrimDefaultPredicate for more information, UsdStage::Traverse(),
876  /// and \c UsdPrimRange for more general Stage traversal behaviors.
877  inline SubtreeRange GetAllDescendants() const;
878 
879  /// Return a subset of all of this prim's descendants filtered by
880  /// \p predicate as an iterable range. The \p predicate is generated by
881  /// combining a series of prim flag terms with either && or || and !.
882  ///
883  /// Example usage:
884  /// \code
885  /// // Get all active model descendants.
886  /// GetFilteredDescendants(UsdPrimIsActive && UsdPrimIsModel);
887  ///
888  /// // Get all model descendants that pass the default predicate.
889  /// GetFilteredDescendants(UsdPrimDefaultPredicate && UsdPrimIsModel);
890  /// \endcode
891  ///
892  /// If this prim is an instance, no descendants will be returned unless
893  /// #UsdTraverseInstanceProxies is used to allow instance proxies to be
894  /// returned, or if this prim is itself an instance proxy.
895  ///
896  /// \note This method is not yet available in python, pending some
897  /// refactoring to make it more feasible.
898  ///
899  /// See \ref Usd_PrimFlags "Prim predicate flags" and
900  /// #UsdPrimDefaultPredicate for more information, UsdStage::Traverse(),
901  /// and \c UsdPrimRange for more general Stage traversal behaviors.
902  inline SubtreeRange
903  GetFilteredDescendants(const Usd_PrimFlagsPredicate &predicate) const;
904 
905 public:
906  // --------------------------------------------------------------------- //
907  /// \name Parent & Stage
908  // --------------------------------------------------------------------- //
909 
910  /// Return this prim's parent prim. Return an invalid UsdPrim if this is a
911  /// root prim.
912  UsdPrim GetParent() const {
914  SdfPath proxyPrimPath = _ProxyPrimPath();
915  Usd_MoveToParent(prim, proxyPrimPath);
916  return UsdPrim(prim, proxyPrimPath);
917  }
918 
919  /// Return this prim's next active, loaded, defined, non-abstract sibling
920  /// if it has one, otherwise return an invalid UsdPrim. Equivalent to:
921  /// \code
922  /// GetFilteredNextSibling(UsdPrimDefaultPredicate)
923  /// \endcode
924  ///
925  /// See \ref Usd_PrimFlags "Prim predicate flags"
926  /// and #UsdPrimDefaultPredicate for more information.
927  USD_API
928  UsdPrim GetNextSibling() const;
929 
930  /// Return this prim's next sibling that matches \p predicate if it has one,
931  /// otherwise return the invalid UsdPrim.
932  ///
933  /// See \ref Usd_PrimFlags "Prim predicate flags"
934  /// and #UsdPrimDefaultPredicate for more information.
935  USD_API
937  const Usd_PrimFlagsPredicate &predicate) const;
938 
939  /// Returns true if the prim is the pseudo root.
940  ///
941  /// Equivalent to
942  /// \code
943  /// prim.GetPath() == SdfPath::AbsoluteRootPath()
944  /// \endcode
945  USD_API
946  bool IsPseudoRoot() const;
947 
948  /// Returns the prim at \p path on the same stage as this prim.
949  /// If path is is relative, it will be anchored to the path of this prim.
950  /// \sa UsdStage::GetPrimAtPath(const SdfPath&) const
951  USD_API UsdPrim GetPrimAtPath(const SdfPath& path) const;
952 
953  /// Returns the object at \p path on the same stage as this prim.
954  /// If path is is relative, it will be anchored to the path of this prim.
955  /// \sa UsdStage::GetObjectAtPath(const SdfPath&) const
957 
958  /// Returns the property at \p path on the same stage as this prim.
959  /// If path is relative, it will be anchored to the path of this prim.
960  ///
961  /// \note There is no guarantee that this method returns a property on
962  /// this prim. This is only guaranteed if path is a purely relative
963  /// property path.
964  /// \sa GetProperty(const TfToken&) const
965  /// \sa UsdStage::GetPropertyAtPath(const SdfPath&) const
967 
968  /// Returns the attribute at \p path on the same stage as this prim.
969  /// If path is relative, it will be anchored to the path of this prim.
970  ///
971  /// \note There is no guarantee that this method returns an attribute on
972  /// this prim. This is only guaranteed if path is a purely relative
973  /// property path.
974  /// \sa GetAttribute(const TfToken&) const
975  /// \sa UsdStage::GetAttributeAtPath(const SdfPath&) const
977 
978  /// Returns the relationship at \p path on the same stage as this prim.
979  /// If path is relative, it will be anchored to the path of this prim.
980  ///
981  /// \note There is no guarantee that this method returns a relationship on
982  /// this prim. This is only guaranteed if path is a purely relative
983  /// property path.
984  /// \sa GetRelationship(const TfToken&) const
985  /// \sa UsdStage::GetRelationshipAtPath(const SdfPath&) const
987 
988  // --------------------------------------------------------------------- //
989  /// \name Variants
990  // --------------------------------------------------------------------- //
991 
992  /// Return a UsdVariantSets object representing all the VariantSets
993  /// present on this prim.
994  ///
995  /// The returned object also provides the API for adding new VariantSets
996  /// to the prim.
997  USD_API
999 
1000  /// Retrieve a specifically named VariantSet for editing or constructing
1001  /// a UsdEditTarget.
1002  ///
1003  /// This is a shortcut for
1004  /// \code
1005  /// prim.GetVariantSets().GetVariantSet(variantSetName)
1006  /// \endcode
1007  USD_API
1008  UsdVariantSet GetVariantSet(const std::string& variantSetName) const;
1009 
1010  /// Return true if this prim has any authored VariantSets.
1011  ///
1012  /// \note this connotes only the *existence* of one of more VariantSets,
1013  /// *not* that such VariantSets necessarily contain any variants or
1014  /// variant opinions.
1015  USD_API
1016  bool HasVariantSets() const;
1017 
1018  // --------------------------------------------------------------------- //
1019  /// \name Attributes
1020  // --------------------------------------------------------------------- //
1021 
1022  /// Author scene description for the attribute named \a attrName at the
1023  /// current EditTarget if none already exists. Return a valid attribute if
1024  /// scene description was successfully authored or if it already existed,
1025  /// return invalid attribute otherwise. Note that the supplied \a typeName
1026  /// and \a custom arguments are only used in one specific case. See below
1027  /// for details.
1028  ///
1029  /// Suggested use:
1030  /// \code
1031  /// if (UsdAttribute myAttr = prim.CreateAttribute(...)) {
1032  /// // success.
1033  /// }
1034  /// \endcode
1035  ///
1036  /// To call this, GetPrim() must return a valid prim.
1037  ///
1038  /// - If a spec for this attribute already exists at the current edit
1039  /// target, do nothing.
1040  ///
1041  /// - If a spec for \a attrName of a different spec type (e.g. a
1042  /// relationship) exists at the current EditTarget, issue an error.
1043  ///
1044  /// - If \a name refers to a builtin attribute according to the prim's
1045  /// definition, author an attribute spec with required metadata from the
1046  /// definition.
1047  ///
1048  /// - If \a name refers to a builtin relationship, issue an error.
1049  ///
1050  /// - If there exists an absolute strongest authored attribute spec for
1051  /// \a attrName, author an attribute spec at the current EditTarget by
1052  /// copying required metadata from that strongest spec.
1053  ///
1054  /// - If there exists an absolute strongest authored relationship spec for
1055  /// \a attrName, issue an error.
1056  ///
1057  /// - Otherwise author an attribute spec at the current EditTarget using
1058  /// the provided \a typeName and \a custom for the required metadata fields.
1059  /// Note that these supplied arguments are only ever used in this particular
1060  /// circumstance, in all other cases they are ignored.
1061  USD_API
1062  UsdAttribute
1063  CreateAttribute(const TfToken& name,
1064  const SdfValueTypeName &typeName,
1065  bool custom,
1066  SdfVariability variability = SdfVariabilityVarying) const;
1067  /// \overload
1068  /// Create a custom attribute with \p name, \p typeName and \p variability.
1069  USD_API
1070  UsdAttribute
1071  CreateAttribute(const TfToken& name,
1072  const SdfValueTypeName &typeName,
1073  SdfVariability variability = SdfVariabilityVarying) const;
1074 
1075  /// \overload
1076  /// This overload of CreateAttribute() accepts a vector of name components
1077  /// used to construct a \em namespaced property name. For details, see
1078  /// \ref Usd_Ordering
1079  USD_API
1081  const std::vector<std::string> &nameElts,
1082  const SdfValueTypeName &typeName,
1083  bool custom,
1084  SdfVariability variability = SdfVariabilityVarying) const;
1085  /// \overload
1086  /// Create a custom attribute with \p nameElts, \p typeName, and
1087  /// \p variability.
1088  USD_API
1090  const std::vector<std::string> &nameElts,
1091  const SdfValueTypeName &typeName,
1092  SdfVariability variability = SdfVariabilityVarying) const;
1093 
1094  /// Like GetProperties(), but exclude all relationships from the result.
1095  USD_API
1096  std::vector<UsdAttribute> GetAttributes() const;
1097 
1098  /// Like GetAttributes(), but exclude attributes without authored scene
1099  /// description from the result. See UsdProperty::IsAuthored().
1100  USD_API
1101  std::vector<UsdAttribute> GetAuthoredAttributes() const;
1102 
1103  /// Return a UsdAttribute with the name \a attrName. The attribute
1104  /// returned may or may not \b actually exist so it must be checked for
1105  /// validity. Suggested use:
1106  ///
1107  /// \code
1108  /// if (UsdAttribute myAttr = prim.GetAttribute("myAttr")) {
1109  /// // myAttr is safe to use.
1110  /// // Edits to the owning stage requires subsequent validation.
1111  /// } else {
1112  /// // myAttr was not defined/authored
1113  /// }
1114  /// \endcode
1115  USD_API
1116  UsdAttribute GetAttribute(const TfToken& attrName) const;
1117 
1118  /// Return true if this prim has an attribute named \p attrName, false
1119  /// otherwise.
1120  USD_API
1121  bool HasAttribute(const TfToken& attrName) const;
1122 
1123  /// Search the prim subtree rooted at this prim for attributes for which
1124  /// \p predicate returns true, collect their connection source paths and
1125  /// return them in an arbitrary order. If \p recurseOnSources is true,
1126  /// act as if this function was invoked on the connected prims and owning
1127  /// prims of connected properties also and return the union.
1128  USD_API
1131  std::function<bool (UsdAttribute const &)> const &pred = nullptr,
1132  bool recurseOnSources = false) const;
1133 
1134  // --------------------------------------------------------------------- //
1135  /// \name Relationships
1136  // --------------------------------------------------------------------- //
1137 
1138  /// Author scene description for the relationship named \a relName at the
1139  /// current EditTarget if none already exists. Return a valid relationship
1140  /// if scene description was successfully authored or if it already existed,
1141  /// return an invalid relationship otherwise.
1142  ///
1143  /// Suggested use:
1144  /// \code
1145  /// if (UsdRelationship myRel = prim.CreateRelationship(...)) {
1146  /// // success.
1147  /// }
1148  /// \endcode
1149  ///
1150  /// To call this, GetPrim() must return a valid prim.
1151  ///
1152  /// - If a spec for this relationship already exists at the current edit
1153  /// target, do nothing.
1154  ///
1155  /// - If a spec for \a relName of a different spec type (e.g. an
1156  /// attribute) exists at the current EditTarget, issue an error.
1157  ///
1158  /// - If \a name refers to a builtin relationship according to the prim's
1159  /// definition, author a relationship spec with required metadata from the
1160  /// definition.
1161  ///
1162  /// - If \a name refers to a builtin attribute, issue an error.
1163  ///
1164  /// - If there exists an absolute strongest authored relationship spec for
1165  /// \a relName, author a relationship spec at the current EditTarget by
1166  /// copying required metadata from that strongest spec.
1167  ///
1168  /// - If there exists an absolute strongest authored attribute spec for \a
1169  /// relName, issue an error.
1170  ///
1171  /// - Otherwise author a uniform relationship spec at the current
1172  /// EditTarget, honoring \p custom .
1173  ///
1174  USD_API
1176  bool custom=true) const;
1177 
1178  /// \overload
1179  /// This overload of CreateRelationship() accepts a vector of
1180  /// name components used to construct a \em namespaced property name.
1181  /// For details, see \ref Usd_Ordering
1182  USD_API
1183  UsdRelationship CreateRelationship(const std::vector<std::string> &nameElts,
1184  bool custom=true)
1185  const;
1186 
1187  /// Like GetProperties(), but exclude all attributes from the result.
1188  USD_API
1189  std::vector<UsdRelationship> GetRelationships() const;
1190 
1191  /// Like GetRelationships(), but exclude relationships without authored
1192  /// scene description from the result. See UsdProperty::IsAuthored().
1193  USD_API
1194  std::vector<UsdRelationship> GetAuthoredRelationships() const;
1195 
1196  /// Return a UsdRelationship with the name \a relName. The relationship
1197  /// returned may or may not \b actually exist so it must be checked for
1198  /// validity. Suggested use:
1199  ///
1200  /// \code
1201  /// if (UsdRelationship myRel = prim.GetRelationship("myRel")) {
1202  /// // myRel is safe to use.
1203  /// // Edits to the owning stage requires subsequent validation.
1204  /// } else {
1205  /// // myRel was not defined/authored
1206  /// }
1207  /// \endcode
1208  USD_API
1209  UsdRelationship GetRelationship(const TfToken& relName) const;
1210 
1211  /// Return true if this prim has a relationship named \p relName, false
1212  /// otherwise.
1213  USD_API
1214  bool HasRelationship(const TfToken& relName) const;
1215 
1216  /// Search the prim subtree rooted at this prim for relationships for which
1217  /// \p predicate returns true, collect their target paths and return them in
1218  /// an arbitrary order. If \p recurseOnTargets is true, act as if this
1219  /// function was invoked on the targeted prims and owning prims of targeted
1220  /// properties also (but not of forwarding relationships) and return the
1221  /// union.
1222  USD_API
1225  std::function<bool (UsdRelationship const &)> const &pred = nullptr,
1226  bool recurseOnTargets = false) const;
1227 
1228  // --------------------------------------------------------------------- //
1229  /// \name Payload Authoring
1230  /// \deprecated
1231  /// This API is now deprecated. Please use the HasAuthoredPayloads and the
1232  /// UsdPayloads API returned from GetPayloads() to query and author payloads
1233  /// instead.
1234  /// @{
1235  // --------------------------------------------------------------------- //
1236 
1237  /// \deprecated
1238  /// Clears the payload at the current EditTarget for this prim. Return false
1239  /// if the payload could not be cleared.
1240  USD_API
1241  bool ClearPayload() const;
1242 
1243  /// \deprecated
1244  /// Return true if a payload is present on this prim.
1245  ///
1246  /// \sa \ref Usd_Payloads
1247  USD_API
1248  bool HasPayload() const;
1249 
1250  /// \deprecated
1251  /// Author payload metadata for this prim at the current edit
1252  /// target. Return true on success, false if the value could not be set.
1253  ///
1254  /// \sa \ref Usd_Payloads
1255  USD_API
1256  bool SetPayload(const SdfPayload& payload) const;
1257 
1258  /// \deprecated
1259  /// Shorthand for SetPayload(SdfPayload(assetPath, primPath)).
1260  USD_API
1261  bool SetPayload(
1262  const std::string& assetPath, const SdfPath& primPath) const;
1263 
1264  /// \deprecated
1265  /// Shorthand for SetPayload(SdfPayload(layer->GetIdentifier(),
1266  /// primPath)).
1267  USD_API
1268  bool SetPayload(const SdfLayerHandle& layer, const SdfPath& primPath) const;
1269 
1270  /// @}
1271 
1272  // --------------------------------------------------------------------- //
1273  /// \name Payloads, Load and Unload
1274  // --------------------------------------------------------------------- //
1275 
1276  /// Return a UsdPayloads object that allows one to add, remove, or
1277  /// mutate payloads <em>at the currently set UsdEditTarget</em>.
1278  ///
1279  /// There is currently no facility for \em listing the currently authored
1280  /// payloads on a prim... the problem is somewhat ill-defined, and
1281  /// requires some thought.
1282  USD_API
1283  UsdPayloads GetPayloads() const;
1284 
1285  /// Return true if this prim has any authored payloads.
1286  USD_API
1287  bool HasAuthoredPayloads() const;
1288 
1289  /// Load this prim, all its ancestors, and by default all its descendants.
1290  /// If \p loadPolicy is UsdLoadWithoutDescendants, then load only this prim
1291  /// and its ancestors.
1292  ///
1293  /// See UsdStage::Load for additional details.
1294  USD_API
1296 
1297  /// Unloads this prim and all its descendants.
1298  ///
1299  /// See UsdStage::Unload for additional details.
1300  USD_API
1301  void Unload() const;
1302 
1303  // --------------------------------------------------------------------- //
1304  /// \name References
1305  // --------------------------------------------------------------------- //
1306 
1307  /// Return a UsdReferences object that allows one to add, remove, or
1308  /// mutate references <em>at the currently set UsdEditTarget</em>.
1309  ///
1310  /// There is currently no facility for \em listing the currently authored
1311  /// references on a prim... the problem is somewhat ill-defined, and
1312  /// requires some thought.
1313  USD_API
1314  UsdReferences GetReferences() const;
1315 
1316  /// Return true if this prim has any authored references.
1317  USD_API
1318  bool HasAuthoredReferences() const;
1319 
1320  // --------------------------------------------------------------------- //
1321  /// \name Inherits
1322  // --------------------------------------------------------------------- //
1323 
1324  /// Return a UsdInherits object that allows one to add, remove, or
1325  /// mutate inherits <em>at the currently set UsdEditTarget</em>.
1326  ///
1327  /// There is currently no facility for \em listing the currently authored
1328  /// inherits on a prim... the problem is somewhat ill-defined, and
1329  /// requires some thought.
1330  USD_API
1331  UsdInherits GetInherits() const;
1332 
1333  /// Return true if this prim has any authored inherits.
1334  USD_API
1335  bool HasAuthoredInherits() const;
1336 
1337  // --------------------------------------------------------------------- //
1338  /// \name Specializes
1339  // --------------------------------------------------------------------- //
1340 
1341  /// Return a UsdSpecializes object that allows one to add, remove, or
1342  /// mutate specializes <em>at the currently set UsdEditTarget</em>.
1343  ///
1344  /// There is currently no facility for \em listing the currently authored
1345  /// specializes on a prim... the problem is somewhat ill-defined, and
1346  /// requires some thought.
1347  USD_API
1349 
1350  /// Returns true if this prim has any authored specializes.
1351  USD_API
1352  bool HasAuthoredSpecializes() const;
1353 
1354  // --------------------------------------------------------------------- //
1355  /// \name Instancing
1356  /// See \ref Usd_Page_ScenegraphInstancing for more details.
1357  /// @{
1358  // --------------------------------------------------------------------- //
1359 
1360  /// Return true if this prim has been marked as instanceable.
1361  ///
1362  /// Note that this is not the same as IsInstance(). A prim may return
1363  /// true for IsInstanceable() and false for IsInstance() if this prim
1364  /// is not active or if it is marked as instanceable but contains no
1365  /// instanceable data.
1366  bool IsInstanceable() const {
1367  bool instanceable = false;
1368  return GetMetadata(SdfFieldKeys->Instanceable, &instanceable) &&
1369  instanceable;
1370  }
1371 
1372  /// Author 'instanceable' metadata for this prim at the current
1373  /// EditTarget.
1374  bool SetInstanceable(bool instanceable) const {
1375  return SetMetadata(SdfFieldKeys->Instanceable, instanceable);
1376  }
1377 
1378  /// Remove the authored 'instanceable' opinion at the current EditTarget.
1379  /// Do nothing if there is no authored opinion.
1380  bool ClearInstanceable() const {
1381  return ClearMetadata(SdfFieldKeys->Instanceable);
1382  }
1383 
1384  /// Return true if this prim has an authored opinion for 'instanceable',
1385  /// false otherwise.
1387  return HasAuthoredMetadata(SdfFieldKeys->Instanceable);
1388  }
1389 
1390  /// Return true if this prim is an instance of a master, false
1391  /// otherwise.
1392  ///
1393  /// If this prim is an instance, calling GetMaster() will return
1394  /// the UsdPrim for the corresponding master prim.
1395  bool IsInstance() const { return _Prim()->IsInstance(); }
1396 
1397  /// Return true if this prim is an instance proxy, false otherwise.
1398  /// An instance proxy prim represents a descendent of an instance
1399  /// prim.
1400  bool IsInstanceProxy() const {
1402  }
1403 
1404  /// Return true if this prim is a master prim, false otherwise.
1405  bool IsMaster() const { return _Prim()->IsMaster(); }
1406 
1407  /// Return true if this prim is located in a subtree of prims
1408  /// rooted at a master prim, false otherwise.
1409  ///
1410  /// If this function returns true, this prim is either a master prim
1411  /// or a descendent of a master prim.
1412  bool IsInMaster() const {
1413  return (IsInstanceProxy() ?
1414  _PrimPathIsInMaster() : _Prim()->IsInMaster());
1415  }
1416 
1417  /// If this prim is an instance, return the UsdPrim for the corresponding
1418  /// master. Otherwise, return an invalid UsdPrim.
1419  USD_API
1420  UsdPrim GetMaster() const;
1421 
1422  /// If this prim is an instance proxy, return the UsdPrim for the
1423  /// corresponding prim in the instance's master. Otherwise, return an
1424  /// invalid UsdPrim.
1426  if (IsInstanceProxy()) {
1427  return UsdPrim(_Prim(), SdfPath());
1428  }
1429  return UsdPrim();
1430  }
1431 
1432  /// If this prim is a master prim, returns all prims that are instances of
1433  /// this master. Otherwise, returns an empty vector.
1434  ///
1435  /// Note that this function will return prims in masters for instances that
1436  /// are nested beneath other instances.
1437  USD_API
1438  std::vector<UsdPrim> GetInstances() const;
1439  /// @}
1440 
1441  // --------------------------------------------------------------------- //
1442  /// \name Composition Structure
1443  /// @{
1444  // --------------------------------------------------------------------- //
1445 
1446  /// Return the cached prim index containing all sites that can contribute
1447  /// opinions to this prim.
1448  ///
1449  /// The prim index can be used to examine the composition arcs and scene
1450  /// description sites that can contribute to this prim's property and
1451  /// metadata values.
1452  ///
1453  /// The prim index returned by this function is optimized and may not
1454  /// include sites that do not contribute opinions to this prim. Use
1455  /// UsdPrim::ComputeExpandedPrimIndex to compute a prim index that includes
1456  /// all possible sites that could contribute opinions.
1457  ///
1458  /// This prim index will be empty for master prims. This ensures that these
1459  /// prims do not provide any attribute or metadata values. For all other
1460  /// prims in masters, this is the prim index that was chosen to be shared
1461  /// with all other instances. In either case, the prim index's path will
1462  /// not be the same as the prim's path.
1463  ///
1464  /// Prim indexes may be invalidated by changes to the UsdStage and cannot
1465  /// detect if they are expired. Clients should avoid keeping copies of the
1466  /// prim index across such changes, which include scene description
1467  /// changes or changes to load state.
1468  const PcpPrimIndex &GetPrimIndex() const { return _Prim()->GetPrimIndex(); }
1469 
1470  /// Compute the prim index containing all sites that could contribute
1471  /// opinions to this prim.
1472  ///
1473  /// This function is similar to UsdPrim::GetPrimIndex. However, the
1474  /// returned prim index includes all sites that could possibly contribute
1475  /// opinions to this prim, not just the sites that currently do so. This is
1476  /// useful in certain situations; for example, this could be used to
1477  /// generate a list of sites where clients could make edits to affect this
1478  /// prim, or for debugging purposes.
1479  ///
1480  /// This function may be relatively slow, since it will recompute the prim
1481  /// index on every call. Clients should prefer UsdPrim::GetPrimIndex unless
1482  /// the additional site information is truly needed.
1483  USD_API
1485 
1486  /// @}
1487 
1488 private:
1489  friend class UsdObject;
1492  friend class UsdProperty;
1493  friend class UsdSchemaBase;
1494  friend class UsdAPISchemaBase;
1495  friend class UsdStage;
1496  friend class UsdPrimRange;
1497  friend class Usd_PrimData;
1501 
1502  // Prim constructor.
1503  UsdPrim(const Usd_PrimDataHandle &primData,
1504  const SdfPath &proxyPrimPath)
1505  : UsdObject(primData, proxyPrimPath) { }
1506 
1507  // General constructor.
1508  UsdPrim(UsdObjType objType,
1509  const Usd_PrimDataHandle &prim,
1510  const SdfPath &proxyPrimPath,
1511  const TfToken &propName)
1512  : UsdObject(objType, prim, proxyPrimPath, propName) {}
1513 
1514  // Helper to make a sibling range.
1515  inline SiblingRange
1516  _MakeSiblingRange(const Usd_PrimFlagsPredicate &pred) const;
1517 
1518  // Helper to make a range of descendants.
1519  inline SubtreeRange
1520  _MakeDescendantsRange(const Usd_PrimFlagsPredicate &pred) const;
1521 
1522  // Helper to make a vector of properties from names.
1523  std::vector<UsdProperty>
1524  _MakeProperties(const TfTokenVector &names) const;
1525 
1526  // Helper for Get{Authored}{PropertyNames,Properties}
1527  TfTokenVector _GetPropertyNames(
1528  bool onlyAuthored,
1529  bool applyOrder=true,
1530  const PropertyPredicateFunc &predicate={}) const;
1531 
1532  // Helper for Get(Authored)PropertiesInNamespace.
1533  std::vector<UsdProperty>
1534  _GetPropertiesInNamespace(const std::string &namespaces,
1535  bool onlyAuthored) const;
1536 
1537  // Helper for Get(Authored)Attributes.
1538  std::vector<UsdAttribute>
1539  _GetAttributes(bool onlyAuthored, bool applyOrder=false) const;
1540 
1541  // Helper for Get(Authored)Relationships.
1542  std::vector<UsdRelationship>
1543  _GetRelationships(bool onlyAuthored, bool applyOrder=false) const;
1544 
1545  // Helper for determining whether this prim is in a master based
1546  // on prim path.
1547  USD_API
1548  bool _PrimPathIsInMaster() const;
1549 
1550  friend const PcpPrimIndex &Usd_PrimGetSourcePrimIndex(const UsdPrim&);
1551  // Return a const reference to the source PcpPrimIndex for this prim.
1552  //
1553  // For all prims in masters (which includes the master prim itself),
1554  // this is the prim index for the instance that was chosen to serve
1555  // as the master for all other instances. This prim index will not
1556  // have the same path as the prim's path.
1557  //
1558  // This is a private helper but is also wrapped out to Python
1559  // for testing and debugging purposes.
1560  const PcpPrimIndex &_GetSourcePrimIndex() const
1561  { return _Prim()->GetSourcePrimIndex(); }
1562 };
1563 
1564 #ifdef doxygen
1565 
1566 /// Forward traversal iterator of sibling ::UsdPrim s. This is a
1567 /// standard-compliant iterator that may be used with STL algorithms, etc.
1568 class UsdPrimSiblingIterator {
1569 public:
1570  /// Iterator value type.
1571  typedef UsdPrim value_type;
1572  /// Iterator reference type, in this case the same as \a value_type.
1573  typedef value_type reference;
1574  /// Iterator difference type.
1575  typedef unspecified-integral-type difference_type;
1576  /// Dereference.
1577  reference operator*() const;
1578  /// Indirection.
1579  unspecified-type operator->() const;
1580  /// Postincrement.
1581  UsdPrimSiblingIterator &operator++();
1582  /// Preincrement.
1583  UsdPrimSiblingIterator operator++(int);
1584 private:
1585  /// Equality.
1586  friend bool operator==(const UsdPrimSiblingIterator &lhs,
1587  const UsdPrimSiblingIterator &rhs);
1588  /// Inequality.
1589  friend bool operator!=(const UsdPrimSiblingIterator &lhs,
1590  const UsdPrimSiblingIterator &rhs);
1591 };
1592 
1593 /// Forward iterator range of sibling ::UsdPrim s. This range type contains a
1594 /// pair of UsdPrimSiblingIterator s, denoting a half-open range of UsdPrim
1595 /// siblings. It provides a subset of container-like API, such as begin(),
1596 /// end(), front(), empty(), etc.
1597 class UsdPrimSiblingRange {
1598 public:
1599  /// Iterator type.
1600  typedef UsdPrimSiblingIterator iterator;
1601  /// Const iterator type.
1602  typedef UsdPrimSiblingIterator const_iterator;
1603  /// Iterator difference type.
1604  typedef unspecified-integral-type difference_type;
1605  /// Iterator value_type.
1607  /// Iterator reference_type.
1609 
1610  /// Construct with a pair of iterators.
1613 
1614  /// Construct/convert from another compatible range type.
1615  template <class ForwardRange>
1616  UsdPrimSiblingRange(const ForwardRange &r);
1617 
1618  /// Assign from another compatible range type.
1619  template <class ForwardRange>
1620  UsdPrimSiblingRange &operator=(const ForwardRange &r);
1621 
1622  /// First iterator.
1623  iterator begin() const;
1624 
1625  /// Past-the-end iterator.
1626  iterator end() const;
1627 
1628  /// Return !empty().
1629  operator unspecified_bool_type() const;
1630 
1631  /// Equality compare.
1632  bool equal(const iterator_range&) const;
1633 
1634  /// Return *begin(). This range must not be empty.
1635  reference front() const;
1636 
1637  /// Advance this range's begin iterator.
1638  iterator_range& advance_begin(difference_type n);
1639 
1640  /// Advance this range's end iterator.
1641  iterator_range& advance_end(difference_type n);
1642 
1643  ; /// Return begin() == end().
1644  bool empty() const;
1645 
1646 private:
1647  /// Equality comparison.
1648  friend bool operator==(const UsdPrimSiblingRange &lhs,
1649  const UsdPrimSiblingRange &rhs);
1650  /// Inequality comparison.
1651  friend bool operator!=(const UsdPrimSiblingRange &lhs,
1652  const UsdPrimSiblingRange &rhs);
1653 };
1654 
1655 #else
1656 
1657 // Sibling iterator class. Converts ref to weak and filters according to a
1658 // supplied predicate.
1659 class UsdPrimSiblingIterator : public hboost::iterator_adaptor<
1660  UsdPrimSiblingIterator, // crtp base.
1661  const Usd_PrimData *, // base iterator.
1662  UsdPrim, // value type.
1663  hboost::forward_traversal_tag, // traversal
1664  UsdPrim> // reference type.
1665 {
1666 public:
1667  // Default ctor.
1669 
1670 private:
1671  friend class UsdPrim;
1672 
1673  // Constructor used by Prim.
1674  UsdPrimSiblingIterator(const base_type &i, const SdfPath& proxyPrimPath,
1675  const Usd_PrimFlagsPredicate &predicate)
1676  : iterator_adaptor_(i)
1677  , _proxyPrimPath(proxyPrimPath)
1678  , _predicate(predicate) {
1679  // Need to advance iterator to first matching element.
1680  if (base() && !Usd_EvalPredicate(_predicate, base(), _proxyPrimPath))
1681  increment();
1682  }
1683 
1684  // Core implementation invoked by iterator_adaptor.
1686  bool equal(const UsdPrimSiblingIterator &other) const {
1687  return base() == other.base() &&
1688  _proxyPrimPath == other._proxyPrimPath &&
1689  _predicate == other._predicate;
1690  }
1691 
1692  void increment() {
1693  base_type &base = base_reference();
1694  if (Usd_MoveToNextSiblingOrParent(base, _proxyPrimPath, _predicate)) {
1695  base = nullptr;
1696  _proxyPrimPath = SdfPath();
1697  }
1698  }
1699 
1700  reference dereference() const {
1701  return UsdPrim(base(), _proxyPrimPath);
1702  }
1703 
1704  SdfPath _proxyPrimPath;
1705  Usd_PrimFlagsPredicate _predicate;
1706 };
1707 
1708 // Typedef iterator range.
1709 typedef hboost::iterator_range<UsdPrimSiblingIterator> UsdPrimSiblingRange;
1710 
1711 // Inform TfIterator it should feel free to make copies of the range type.
1712 template <>
1714  UsdPrimSiblingRange> : hboost::true_type {};
1715 template <>
1717  const UsdPrimSiblingRange> : hboost::true_type {};
1718 
1719 #endif // doxygen
1720 
1721 
1722 UsdPrimSiblingRange
1724 {
1725  return _MakeSiblingRange(
1727 }
1728 
1729 UsdPrimSiblingRange
1731 {
1733 }
1734 
1735 UsdPrimSiblingRange
1737 {
1739 }
1740 
1741 // Helper to make a sibling range.
1743 UsdPrim::_MakeSiblingRange(const Usd_PrimFlagsPredicate &pred) const {
1744  Usd_PrimDataConstPtr firstChild = get_pointer(_Prim());
1745  SdfPath firstChildPath = _ProxyPrimPath();
1746  if (!Usd_MoveToChild(firstChild, firstChildPath, pred)) {
1747  firstChild = nullptr;
1748  firstChildPath = SdfPath();
1749  }
1750 
1751  return SiblingRange(
1752  SiblingIterator(firstChild, firstChildPath, pred),
1753  SiblingIterator(nullptr, SdfPath(), pred));
1754 }
1755 
1756 #ifdef doxygen
1757 
1758 /// Forward traversal iterator of sibling ::UsdPrim s. This is a
1759 /// standard-compliant iterator that may be used with STL algorithms, etc.
1760 class UsdPrimSubtreeIterator {
1761 public:
1762  /// Iterator value type.
1763  typedef UsdPrim value_type;
1764  /// Iterator reference type, in this case the same as \a value_type.
1765  typedef value_type reference;
1766  /// Iterator difference type.
1767  typedef unspecified-integral-type difference_type;
1768  /// Dereference.
1769  reference operator*() const;
1770  /// Indirection.
1771  unspecified-type operator->() const;
1772  /// Postincrement.
1773  UsdPrimSubtreeIterator &operator++();
1774  /// Preincrement.
1775  UsdPrimSubtreeIterator operator++(int);
1776 private:
1777  /// Equality.
1778  friend bool operator==(const UsdPrimSubtreeIterator &lhs,
1779  const UsdPrimSubtreeIterator &rhs);
1780  /// Inequality.
1781  friend bool operator!=(const UsdPrimSubtreeIterator &lhs,
1782  const UsdPrimSubtreeIterator &rhs);
1783 };
1784 
1785 /// Forward iterator range of sibling ::UsdPrim s. This range type contains a
1786 /// pair of UsdPrimSubtreeIterator s, denoting a half-open range of UsdPrim
1787 /// siblings. It provides a subset of container-like API, such as begin(),
1788 /// end(), front(), empty(), etc.
1789 class UsdPrimSubtreeRange {
1790 public:
1791  /// Iterator type.
1792  typedef UsdPrimSubtreeIterator iterator;
1793  /// Const iterator type.
1794  typedef UsdPrimSubtreeIterator const_iterator;
1795  /// Iterator difference type.
1796  typedef unspecified-integral-type difference_type;
1797  /// Iterator value_type.
1799  /// Iterator reference_type.
1801 
1802  /// Construct with a pair of iterators.
1805 
1806  /// Construct/convert from another compatible range type.
1807  template <class ForwardRange>
1808  UsdPrimSubtreeRange(const ForwardRange &r);
1809 
1810  /// Assign from another compatible range type.
1811  template <class ForwardRange>
1812  UsdPrimSubtreeRange &operator=(const ForwardRange &r);
1813 
1814  /// First iterator.
1815  iterator begin() const;
1816 
1817  /// Past-the-end iterator.
1818  iterator end() const;
1819 
1820  /// Return !empty().
1821  operator unspecified_bool_type() const;
1822 
1823  /// Equality compare.
1824  bool equal(const iterator_range&) const;
1825 
1826  /// Return *begin(). This range must not be empty.
1827  reference front() const;
1828 
1829  /// Advance this range's begin iterator.
1830  iterator_range& advance_begin(difference_type n);
1831 
1832  /// Advance this range's end iterator.
1833  iterator_range& advance_end(difference_type n);
1834 
1835  /// Return begin() == end().
1836  bool empty() const;
1837 
1838 private:
1839  /// Equality comparison.
1840  friend bool operator==(const UsdPrimSubtreeRange &lhs,
1841  const UsdPrimSubtreeRange &rhs);
1842  /// Inequality comparison.
1843  friend bool operator!=(const UsdPrimSubtreeRange &lhs,
1844  const UsdPrimSubtreeRange &rhs);
1845 };
1846 
1847 #else
1848 
1849 // Subtree iterator class. Converts ref to weak and filters according to a
1850 // supplied predicate.
1851 class UsdPrimSubtreeIterator : public hboost::iterator_adaptor<
1852  UsdPrimSubtreeIterator, // crtp base.
1853  const Usd_PrimData *, // base iterator.
1854  UsdPrim, // value type.
1855  hboost::forward_traversal_tag, // traversal
1856  UsdPrim> // reference type.
1857 {
1858 public:
1859  // Default ctor.
1861 
1862 private:
1863  friend class UsdPrim;
1864 
1865  // Constructor used by Prim.
1866  UsdPrimSubtreeIterator(const base_type &i, const SdfPath &proxyPrimPath,
1867  const Usd_PrimFlagsPredicate &predicate)
1868  : iterator_adaptor_(i)
1869  , _proxyPrimPath(proxyPrimPath)
1870  , _predicate(predicate) {
1871  // Need to advance iterator to first matching element.
1872  base_type &base = base_reference();
1873  if (base && !Usd_EvalPredicate(_predicate, base, _proxyPrimPath)) {
1874  if (Usd_MoveToNextSiblingOrParent(base, _proxyPrimPath,
1875  _predicate)) {
1876  base = nullptr;
1877  _proxyPrimPath = SdfPath();
1878  }
1879  }
1880  }
1881 
1882  // Core implementation invoked by iterator_adaptor.
1884  bool equal(const UsdPrimSubtreeIterator &other) const {
1885  return base() == other.base() &&
1886  _proxyPrimPath == other._proxyPrimPath &&
1887  _predicate == other._predicate;
1888  }
1889 
1890  void increment() {
1891  base_type &base = base_reference();
1892  if (!Usd_MoveToChild(base, _proxyPrimPath, _predicate)) {
1893  while (Usd_MoveToNextSiblingOrParent(base, _proxyPrimPath,
1894  _predicate)) {}
1895  }
1896  }
1897 
1898  reference dereference() const {
1899  return UsdPrim(base(), _proxyPrimPath);
1900  }
1901 
1902  SdfPath _proxyPrimPath;
1903  Usd_PrimFlagsPredicate _predicate;
1904 };
1905 
1906 // Typedef iterator range.
1907 typedef hboost::iterator_range<UsdPrimSubtreeIterator> UsdPrimSubtreeRange;
1908 
1909 // Inform TfIterator it should feel free to make copies of the range type.
1910 template <>
1912  UsdPrimSubtreeRange> : hboost::true_type {};
1913 template <>
1915  const UsdPrimSubtreeRange> : hboost::true_type {};
1916 
1917 #endif // doxygen
1918 
1919 UsdPrimSubtreeRange
1921 {
1922  return _MakeDescendantsRange(
1924 }
1925 
1926 UsdPrimSubtreeRange
1928 {
1930 }
1931 
1932 UsdPrimSubtreeRange
1934 {
1936 }
1937 
1938 // Helper to make a sibling range.
1940 UsdPrim::_MakeDescendantsRange(const Usd_PrimFlagsPredicate &pred) const {
1941  Usd_PrimDataConstPtr firstChild = get_pointer(_Prim());
1942  SdfPath firstChildPath = _ProxyPrimPath();
1943  Usd_PrimDataConstPtr endChild = firstChild;
1944  SdfPath endChildPath = firstChildPath;
1945  if (Usd_MoveToChild(firstChild, firstChildPath, pred)) {
1946  while (Usd_MoveToNextSiblingOrParent(endChild, endChildPath, pred)) {}
1947  }
1948 
1949  return SubtreeRange(
1950  SubtreeIterator(firstChild, firstChildPath, pred),
1951  SubtreeIterator(endChild, endChildPath, pred));
1952 }
1953 
1954 
1955 ////////////////////////////////////////////////////////////////////////
1956 // UsdObject methods that require UsdPrim be a complete type.
1957 
1958 inline UsdPrim
1960 {
1961  return UsdPrim(_prim, _proxyPrimPath);
1962 }
1963 
1965 
1966 #endif // PXR_USD_USD_PRIM_H
1967 
USD_API SdfPrimSpecHandleVector GetPrimStack() const
void Usd_MoveToParent(PrimDataPtr &p, SdfPath &proxyPrimPath)
Definition: primData.h:513
friend class UsdPrim
Definition: prim.h:1671
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
Usd_PrimFlagsPredicate Usd_CreatePredicateForTraversal(const PrimDataPtr &p, const SdfPath &proxyPrimPath, Usd_PrimFlagsPredicate pred)
Definition: primData.h:493
GLuint const GLchar * name
Definition: glew.h:1814
#define USD_API
Definition: api.h:40
friend class hboost::iterator_core_access
Definition: prim.h:1883
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.
USD_API UsdVariantSet GetVariantSet(const std::string &variantSetName) const
FMT_CONSTEXPR auto begin(const C &c) -> decltype(c.begin())
Definition: format.h:251
USD_API std::vector< UsdAttribute > GetAuthoredAttributes() const
SiblingRange GetChildren() const
Definition: prim.h:1736
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:1386
UsdPrimSiblingRange SiblingRange
Definition: prim.h:137
USD_API UsdRelationship CreateRelationship(const TfToken &relName, bool custom=true) const
#define TF_CODING_ERROR
SiblingRange GetAllChildren() const
Return all this prim's children as an iterable range.
Definition: prim.h:1730
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:1400
SubtreeRange GetAllDescendants() const
Definition: prim.h:1927
USD_API bool HasAuthoredReferences() const
Return true if this prim has any authored references.
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
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
USD_API UsdPrim GetMaster() 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
GLuint GLdouble GLdouble GLint GLint order
Definition: glew.h:3446
bool IsDefined() const
Definition: prim.h:265
bool HasAPI(const TfToken &instanceName=TfToken()) const
Definition: prim.h:555
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:1500
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:504
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
bool RemoveAPI(const TfToken &instanceName) const
Definition: prim.h:726
Definition: token.h:87
USD_API UsdProperty GetProperty(const TfToken &propName) const
bool IsMaster() const
Return true if this prim is a master prim, false otherwise.
Definition: prim.h:1405
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
Multiple Apply API Schema.
bool Usd_IsInstanceProxy(const PrimDataPtr &p, const SdfPath &proxyPrimPath)
Definition: primData.h:479
USD_API bool HasAuthoredSpecializes() const
Returns true if this prim has any authored specializes.
USD_API UsdReferences GetReferences() const
GLuint GLuint end
Definition: glew.h:1253
friend class hboost::iterator_core_access
Definition: prim.h:1685
bool SetInstanceable(bool instanceable) const
Definition: prim.h:1374
USD_API UsdAttribute GetAttributeAtPath(const SdfPath &path) const
bool HasAuthoredActive() const
Definition: prim.h:242
GLuint const GLuint * names
Definition: glew.h:2690
GLsizei n
Definition: glew.h:4040
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:638
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:446
Single Apply API schema.
friend struct UsdPrim_RelTargetFinder
Definition: prim.h:1499
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
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:1380
USD_API TfTokenVector GetAppliedSchemas() const
GLuint GLuint GLsizei GLenum type
Definition: glew.h:1253
UsdPrim GetParent() const
Definition: prim.h:912
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
USD_API void SetPropertyOrder(const TfTokenVector &order) const
bool Usd_MoveToChild(PrimDataPtr &p, SdfPath &proxyPrimPath, PrimDataPtr end, const Usd_PrimFlagsPredicate &pred)
Definition: primData.h:600
USD_API TfTokenVector GetAuthoredPropertyNames(const PropertyPredicateFunc &predicate={}) const
USD_API UsdInherits GetInherits() const
bool RemoveAPI() const
Definition: prim.h:692
USD_API UsdPrim GetNextSibling() const
SdfVariability
Definition: types.h:179
GLsizei const GLchar *const * path
Definition: glew.h:6461
USD_API UsdVariantSets GetVariantSets() const
friend class UsdPrim
Definition: prim.h:1863
const Usd_PrimDataHandle & _Prim() const
Definition: object.h:695
UsdPrim GetPrim() const
Definition: prim.h:1959
SubtreeRange GetDescendants() const
Definition: prim.h:1933
GLsizei const GLchar *const * string
Definition: glew.h:1844
USD_API std::vector< UsdRelationship > GetRelationships() const
Like GetProperties(), but exclude all attributes from the result.
bool IsInstance() const
Definition: prim.h:1395
SubtreeRange GetFilteredDescendants(const Usd_PrimFlagsPredicate &predicate) const
Definition: prim.h:1920
UsdLoadPolicy
Definition: common.h:116
USD_API const Usd_PrimFlagsConjunction UsdPrimDefaultPredicate
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
bool ClearActive() const
Definition: prim.h:234
hboost::iterator_range< UsdPrimSiblingIterator > UsdPrimSiblingRange
Definition: prim.h:72
bool ApplyAPI() const
Definition: prim.h:605
USD_API const Usd_PrimFlagsPredicate UsdPrimAllPrimsPredicate
UsdPrim GetPrimInMaster() const
Definition: prim.h:1425
bool Usd_MoveToNextSiblingOrParent(PrimDataPtr &p, SdfPath &proxyPrimPath, PrimDataPtr end, const Usd_PrimFlagsPredicate &pred)
Definition: primData.h:543
const PcpPrimIndex & GetPrimIndex() const
Definition: prim.h:1468
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:1366
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 UsdSpecializes GetSpecializes() const
GLdouble GLdouble GLdouble r
Definition: glew.h:1406
const TfToken & GetTypeName() const
Definition: prim.h:197
GLint GLboolean GLint layer
Definition: glew.h:3601
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USD_API UsdRelationship GetRelationship(const TfToken &relName) const
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
GLenum const void GLuint GLint reference
Definition: glew.h:13644
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
bool IsInMaster() const
Definition: prim.h:1412
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
GLsizei const GLfloat * value
Definition: glew.h:1849
UsdPrimSubtreeRange SubtreeRange
Definition: prim.h:141
USD_API bool HasPayload() const
UsdPrimSiblingIterator SiblingIterator
Convenience typedefs.
Definition: prim.h:136
SiblingRange GetFilteredChildren(const Usd_PrimFlagsPredicate &predicate) const
Definition: prim.h:1723
bool IsEmpty() const
Returns true iff this token contains the empty string "".
Definition: token.h:302
friend const PcpPrimIndex & Usd_PrimGetSourcePrimIndex(const UsdPrim &)
USD_API bool IsPseudoRoot() const