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 USD_PRIM_H
25 #define USD_PRIM_H
26 
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 
38 #include "pxr/base/tf/declarePtrs.h"
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 <boost/iterator/iterator_adaptor.hpp>
46 #include <boost/range/iterator_range.hpp>
47 
48 #include <string>
49 #include <type_traits>
50 #include <vector>
51 
52 PXR_NAMESPACE_OPEN_SCOPE
53 
54 class UsdPrim;
55 class UsdPrimRange;
56 class Usd_PrimData;
57 
58 class UsdAttribute;
59 class UsdRelationship;
60 class UsdPayloads;
61 class UsdReferences;
62 class UsdSchemaBase;
63 class UsdAPISchemaBase;
64 class UsdInherits;
65 class UsdSpecializes;
66 class UsdVariantSets;
67 class UsdVariantSet;
68 
69 class SdfPayload;
70 
72 typedef boost::iterator_range<UsdPrimSiblingIterator> UsdPrimSiblingRange;
73 
75 typedef boost::iterator_range<UsdPrimSubtreeIterator> UsdPrimSubtreeRange;
76 
131 class UsdPrim : public UsdObject
132 {
133 public:
137 
141 
144 
147  USD_API
148  SdfPrimSpecHandle GetPrimDefinition() const;
149 
151  SdfSpecifier GetSpecifier() const { return _Prim()->GetSpecifier(); };
152 
162  USD_API
163  SdfPrimSpecHandleVector GetPrimStack() const;
164 
167  bool SetSpecifier(SdfSpecifier specifier) const {
168  return SetMetadata(SdfFieldKeys->Specifier, specifier);
169  }
170 
173  const TfToken &GetTypeName() const { return _Prim()->GetTypeName(); };
174 
176  bool SetTypeName(const TfToken & typeName) const {
177  return SetMetadata(SdfFieldKeys->TypeName, typeName);
178  }
179 
182  bool ClearTypeName() const {
183  return ClearMetadata(SdfFieldKeys->TypeName);
184  }
185 
187  bool HasAuthoredTypeName() const {
188  return HasAuthoredMetadata(SdfFieldKeys->TypeName);
189  }
190 
195  bool IsActive() const { return _Prim()->IsActive(); }
196 
201  bool SetActive(bool active) const {
202  return SetMetadata(SdfFieldKeys->Active, active);
203  }
204 
210  bool ClearActive() const {
211  return ClearMetadata(SdfFieldKeys->Active);
212  }
213 
218  bool HasAuthoredActive() const {
219  return HasAuthoredMetadata(SdfFieldKeys->Active);
220  }
221 
225  bool IsLoaded() const { return _Prim()->IsLoaded(); }
226 
229  bool IsModel() const { return _Prim()->IsModel(); }
230 
234  bool IsGroup() const { return _Prim()->IsGroup(); }
235 
237  bool IsAbstract() const { return _Prim()->IsAbstract(); }
238 
241  bool IsDefined() const { return _Prim()->IsDefined(); }
242 
245  bool HasDefiningSpecifier() const {
246  return _Prim()->HasDefiningSpecifier();
247  }
248 
252  USD_API
254 
257  using PropertyPredicateFunc =
258  std::function<bool (const TfToken &propertyName)>;
259 
271  USD_API
273  const PropertyPredicateFunc &predicate={}) const;
274 
288  USD_API
290  const PropertyPredicateFunc &predicate={}) const;
291 
335  USD_API
336  std::vector<UsdProperty> GetProperties(
337  const PropertyPredicateFunc &predicate={}) const;
338 
352  USD_API
353  std::vector<UsdProperty> GetAuthoredProperties(
354  const PropertyPredicateFunc &predicate={}) const;
355 
367  USD_API
368  std::vector<UsdProperty>
369  GetPropertiesInNamespace(const std::vector<std::string> &namespaces) const;
370 
375  USD_API
376  std::vector<UsdProperty>
377  GetPropertiesInNamespace(const std::string &namespaces) const;
378 
384  USD_API
385  std::vector<UsdProperty>
387  const std::vector<std::string> &namespaces) const;
388 
394  USD_API
395  std::vector<UsdProperty>
396  GetAuthoredPropertiesInNamespace(const std::string &namespaces) const;
397 
399  USD_API
401 
404  USD_API
405  void SetPropertyOrder(const TfTokenVector &order) const;
406 
410  USD_API
411  bool RemoveProperty(const TfToken &propName);
412 
425  USD_API
426  UsdProperty GetProperty(const TfToken &propName) const;
427 
430  USD_API
431  bool HasProperty(const TfToken &propName) const;
432 
433 private:
434  // The non-templated implementation of UsdPrim::IsA using the
435  // TfType system. \p validateSchemaType is provided for python clients
436  // because they can't use compile time assertions on the input type.
437  USD_API
438  bool _IsA(const TfType& schemaType, bool validateSchemaType) const;
439 
440  // The non-templated implementation of UsdPrim::HasAPI using the
441  // TfType system.
442  //
443  // \p validateSchemaType is provided for python clients
444  // because they can't use compile time assertions on the input type.
445  //
446  // \p instanceName is used to determine whether a particular instance
447  // of a multiple-apply API schema has been applied to the prim.
448  USD_API
449  bool _HasAPI(const TfType& schemaType, bool validateSchemaType,
450  const TfToken &instanceName) const;
451 
452 public:
457  template <typename T>
458  bool IsA() const {
459  static_assert(std::is_base_of<UsdSchemaBase, T>::value,
460  "Provided type must derive UsdSchemaBase.");
461  return _IsA(TfType::Find<T>(), /*validateSchemaType=*/false);
462  };
463 
465  USD_API
466  bool IsA(const TfType& schemaType) const;
467 
505  template <typename T>
506  bool HasAPI(const TfToken &instanceName=TfToken()) const {
507  static_assert(std::is_base_of<UsdAPISchemaBase, T>::value,
508  "Provided type must derive UsdAPISchemaBase.");
509  static_assert(!std::is_same<UsdAPISchemaBase, T>::value,
510  "Provided type must not be UsdAPISchemaBase.");
511  static_assert(
512  (T::schemaType == UsdSchemaType::SingleApplyAPI
513  || T::schemaType == UsdSchemaType::MultipleApplyAPI),
514  "Provided schema type must be an applied API schema.");
515 
516  if (T::schemaType != UsdSchemaType::MultipleApplyAPI
517  && !instanceName.IsEmpty()) {
518  TF_CODING_ERROR("HasAPI: single application API schemas like %s do "
519  "not contain an application instanceName ( %s ).",
520  TfType::GetCanonicalTypeName(typeid(T)).c_str(),
521  instanceName.GetText());
522  return false;
523  }
524 
525  return _HasAPI(TfType::Find<T>(), /*validateSchemaType=*/false,
526  instanceName);
527  }
528 
536  USD_API
537  bool HasAPI(const TfType& schemaType,
538  const TfToken& instanceName=TfToken()) const;
539 
540  // --------------------------------------------------------------------- //
542  // --------------------------------------------------------------------- //
543 
549  USD_API
550  UsdPrim GetChild(const TfToken &name) const;
551 
560  inline SiblingRange GetChildren() const;
561 
563  inline SiblingRange GetAllChildren() const;
564 
584  inline SiblingRange
585  GetFilteredChildren(const Usd_PrimFlagsPredicate &predicate) const;
586 
599  inline SubtreeRange GetDescendants() const;
600 
609  inline SubtreeRange GetAllDescendants() const;
610 
634  inline SubtreeRange
635  GetFilteredDescendants(const Usd_PrimFlagsPredicate &predicate) const;
636 
637 public:
638  // --------------------------------------------------------------------- //
640  // --------------------------------------------------------------------- //
641 
644  UsdPrim GetParent() const {
645  Usd_PrimDataConstPtr prim = get_pointer(_Prim());
646  SdfPath proxyPrimPath = _ProxyPrimPath();
647  Usd_MoveToParent(prim, proxyPrimPath);
648  return UsdPrim(prim, proxyPrimPath);
649  }
650 
659  USD_API
660  UsdPrim GetNextSibling() const;
661 
667  USD_API
669  const Usd_PrimFlagsPredicate &predicate) const;
670 
677  USD_API
678  bool IsPseudoRoot() const;
679 
680  // --------------------------------------------------------------------- //
682  // --------------------------------------------------------------------- //
683 
689  USD_API
691 
699  USD_API
700  UsdVariantSet GetVariantSet(const std::string& variantSetName) const;
701 
707  USD_API
708  bool HasVariantSets() const;
709 
710  // --------------------------------------------------------------------- //
712  // --------------------------------------------------------------------- //
713 
753  USD_API
755  CreateAttribute(const TfToken& name,
756  const SdfValueTypeName &typeName,
757  bool custom,
758  SdfVariability variability = SdfVariabilityVarying) const;
761  USD_API
763  CreateAttribute(const TfToken& name,
764  const SdfValueTypeName &typeName,
765  SdfVariability variability = SdfVariabilityVarying) const;
766 
771  USD_API
773  const std::vector<std::string> &nameElts,
774  const SdfValueTypeName &typeName,
775  bool custom,
776  SdfVariability variability = SdfVariabilityVarying) const;
780  USD_API
782  const std::vector<std::string> &nameElts,
783  const SdfValueTypeName &typeName,
784  SdfVariability variability = SdfVariabilityVarying) const;
785 
787  USD_API
788  std::vector<UsdAttribute> GetAttributes() const;
789 
792  USD_API
793  std::vector<UsdAttribute> GetAuthoredAttributes() const;
794 
807  USD_API
808  UsdAttribute GetAttribute(const TfToken& attrName) const;
809 
812  USD_API
813  bool HasAttribute(const TfToken& attrName) const;
814 
820  USD_API
821  SdfPathVector
823  std::function<bool (UsdAttribute const &)> const &pred = nullptr,
824  bool recurseOnSources = false) const;
825 
826  // --------------------------------------------------------------------- //
828  // --------------------------------------------------------------------- //
829 
866  USD_API
868  bool custom=true) const;
869 
874  USD_API
875  UsdRelationship CreateRelationship(const std::vector<std::string> &nameElts,
876  bool custom=true)
877  const;
878 
880  USD_API
881  std::vector<UsdRelationship> GetRelationships() const;
882 
885  USD_API
886  std::vector<UsdRelationship> GetAuthoredRelationships() const;
887 
900  USD_API
901  UsdRelationship GetRelationship(const TfToken& relName) const;
902 
905  USD_API
906  bool HasRelationship(const TfToken& relName) const;
907 
914  USD_API
915  SdfPathVector
917  std::function<bool (UsdRelationship const &)> const &pred = nullptr,
918  bool recurseOnTargets = false) const;
919 
920  // --------------------------------------------------------------------- //
927  // --------------------------------------------------------------------- //
928 
932  USD_API
933  bool ClearPayload() const;
934 
939  USD_API
940  bool HasPayload() const;
941 
947  USD_API
948  bool SetPayload(const SdfPayload& payload) const;
949 
952  USD_API
953  bool SetPayload(
954  const std::string& assetPath, const SdfPath& primPath) const;
955 
959  USD_API
960  bool SetPayload(const SdfLayerHandle& layer, const SdfPath& primPath) const;
961 
963 
964  // --------------------------------------------------------------------- //
966  // --------------------------------------------------------------------- //
967 
974  USD_API
975  UsdPayloads GetPayloads() const;
976 
978  USD_API
979  bool HasAuthoredPayloads() const;
980 
986  USD_API
987  void Load(UsdLoadPolicy policy = UsdLoadWithDescendants) const;
988 
992  USD_API
993  void Unload() const;
994 
995  // --------------------------------------------------------------------- //
997  // --------------------------------------------------------------------- //
998 
1005  USD_API
1006  UsdReferences GetReferences() const;
1007 
1009  USD_API
1010  bool HasAuthoredReferences() const;
1011 
1012  // --------------------------------------------------------------------- //
1014  // --------------------------------------------------------------------- //
1015 
1022  USD_API
1023  UsdInherits GetInherits() const;
1024 
1026  USD_API
1027  bool HasAuthoredInherits() const;
1028 
1029  // --------------------------------------------------------------------- //
1031  // --------------------------------------------------------------------- //
1032 
1039  USD_API
1041 
1043  USD_API
1044  bool HasAuthoredSpecializes() const;
1045 
1046  // --------------------------------------------------------------------- //
1050  // --------------------------------------------------------------------- //
1051 
1058  bool IsInstanceable() const {
1059  bool instanceable = false;
1060  return GetMetadata(SdfFieldKeys->Instanceable, &instanceable) &&
1061  instanceable;
1062  }
1063 
1066  bool SetInstanceable(bool instanceable) const {
1067  return SetMetadata(SdfFieldKeys->Instanceable, instanceable);
1068  }
1069 
1072  bool ClearInstanceable() const {
1073  return ClearMetadata(SdfFieldKeys->Instanceable);
1074  }
1075 
1079  return HasAuthoredMetadata(SdfFieldKeys->Instanceable);
1080  }
1081 
1087  bool IsInstance() const { return _Prim()->IsInstance(); }
1088 
1092  bool IsInstanceProxy() const {
1093  return Usd_IsInstanceProxy(_Prim(), _ProxyPrimPath());
1094  }
1095 
1097  bool IsMaster() const { return _Prim()->IsMaster(); }
1098 
1104  bool IsInMaster() const {
1105  return (IsInstanceProxy() ?
1106  _PrimPathIsInMaster() : _Prim()->IsInMaster());
1107  }
1108 
1111  USD_API
1112  UsdPrim GetMaster() const;
1113 
1118  if (IsInstanceProxy()) {
1119  return UsdPrim(_Prim(), SdfPath());
1120  }
1121  return UsdPrim();
1122  }
1123 
1125 
1126  // --------------------------------------------------------------------- //
1129  // --------------------------------------------------------------------- //
1130 
1153  const PcpPrimIndex &GetPrimIndex() const { return _Prim()->GetPrimIndex(); }
1154 
1168  USD_API
1170 
1172 
1173 private:
1174  friend class UsdObject;
1175  friend class UsdPrimSiblingIterator;
1176  friend class UsdPrimSubtreeIterator;
1177  friend class UsdProperty;
1178  friend class UsdSchemaBase;
1179  friend class UsdAPISchemaBase;
1180  friend class UsdStage;
1181  friend class UsdPrimRange;
1182  friend class Usd_PrimData;
1183  friend class Usd_PrimFlagsPredicate;
1184  friend struct UsdPrim_RelTargetFinder;
1185  friend struct UsdPrim_AttrConnectionFinder;
1186 
1187  // Prim constructor.
1188  UsdPrim(const Usd_PrimDataHandle &primData,
1189  const SdfPath &proxyPrimPath)
1190  : UsdObject(primData, proxyPrimPath) { }
1191 
1192  // General constructor.
1193  UsdPrim(UsdObjType objType,
1194  const Usd_PrimDataHandle &prim,
1195  const SdfPath &proxyPrimPath,
1196  const TfToken &propName)
1197  : UsdObject(objType, prim, proxyPrimPath, propName) {}
1198 
1199  // Helper to make a sibling range.
1200  inline SiblingRange
1201  _MakeSiblingRange(const Usd_PrimFlagsPredicate &pred) const;
1202 
1203  // Helper to make a range of descendants.
1204  inline SubtreeRange
1205  _MakeDescendantsRange(const Usd_PrimFlagsPredicate &pred) const;
1206 
1207  // Helper to make a vector of properties from names.
1208  std::vector<UsdProperty>
1209  _MakeProperties(const TfTokenVector &names) const;
1210 
1211  // Helper for Get{Authored}{PropertyNames,Properties}
1212  TfTokenVector _GetPropertyNames(
1213  bool onlyAuthored,
1214  bool applyOrder=true,
1215  const PropertyPredicateFunc &predicate={}) const;
1216 
1217  // Helper for Get(Authored)PropertiesInNamespace.
1218  std::vector<UsdProperty>
1219  _GetPropertiesInNamespace(const std::string &namespaces,
1220  bool onlyAuthored) const;
1221 
1222  // Helper for Get(Authored)Attributes.
1223  std::vector<UsdAttribute>
1224  _GetAttributes(bool onlyAuthored, bool applyOrder=false) const;
1225 
1226  // Helper for Get(Authored)Relationships.
1227  std::vector<UsdRelationship>
1228  _GetRelationships(bool onlyAuthored, bool applyOrder=false) const;
1229 
1230  // Helper for determining whether this prim is in a master based
1231  // on prim path.
1232  USD_API
1233  bool _PrimPathIsInMaster() const;
1234 
1235  friend const PcpPrimIndex &Usd_PrimGetSourcePrimIndex(const UsdPrim&);
1236  // Return a const reference to the source PcpPrimIndex for this prim.
1237  //
1238  // For all prims in masters (which includes the master prim itself),
1239  // this is the prim index for the instance that was chosen to serve
1240  // as the master for all other instances. This prim index will not
1241  // have the same path as the prim's path.
1242  //
1243  // This is a private helper but is also wrapped out to Python
1244  // for testing and debugging purposes.
1245  const PcpPrimIndex &_GetSourcePrimIndex() const
1246  { return _Prim()->GetSourcePrimIndex(); }
1247 };
1248 
1249 #ifdef doxygen
1250 
1254 public:
1260  typedef unspecified-integral-type difference_type;
1262  reference operator*() const;
1264  unspecified-type operator->() const;
1269 private:
1271  friend bool operator==(const UsdPrimSiblingIterator &lhs,
1272  const UsdPrimSiblingIterator &rhs);
1274  friend bool operator!=(const UsdPrimSiblingIterator &lhs,
1275  const UsdPrimSiblingIterator &rhs);
1276 };
1277 
1283 public:
1289  typedef unspecified-integral-type difference_type;
1294 
1298 
1300  template <class ForwardRange>
1301  UsdPrimSiblingRange(const ForwardRange &r);
1302 
1304  template <class ForwardRange>
1305  UsdPrimSiblingRange &operator=(const ForwardRange &r);
1306 
1308  iterator begin() const;
1309 
1311  iterator end() const;
1312 
1314  operator unspecified_bool_type() const;
1315 
1317  bool equal(const iterator_range&) const;
1318 
1320  reference front() const;
1321 
1323  iterator_range& advance_begin(difference_type n);
1324 
1326  iterator_range& advance_end(difference_type n);
1327 
1328  ;
1329  bool empty() const;
1330 
1331 private:
1333  friend bool operator==(const UsdPrimSiblingRange &lhs,
1334  const UsdPrimSiblingRange &rhs);
1336  friend bool operator!=(const UsdPrimSiblingRange &lhs,
1337  const UsdPrimSiblingRange &rhs);
1338 };
1339 
1340 #else
1341 
1342 // Sibling iterator class. Converts ref to weak and filters according to a
1343 // supplied predicate.
1344 class UsdPrimSiblingIterator : public boost::iterator_adaptor<
1345  UsdPrimSiblingIterator, // crtp base.
1346  const Usd_PrimData *, // base iterator.
1347  UsdPrim, // value type.
1348  boost::forward_traversal_tag, // traversal
1349  UsdPrim> // reference type.
1350 {
1351 public:
1352  // Default ctor.
1354 
1355 private:
1356  friend class UsdPrim;
1357 
1358  // Constructor used by Prim.
1359  UsdPrimSiblingIterator(const base_type &i, const SdfPath& proxyPrimPath,
1360  const Usd_PrimFlagsPredicate &predicate)
1361  : iterator_adaptor_(i)
1362  , _proxyPrimPath(proxyPrimPath)
1363  , _predicate(predicate) {
1364  // Need to advance iterator to first matching element.
1365  if (base() && !Usd_EvalPredicate(_predicate, base(), _proxyPrimPath))
1366  increment();
1367  }
1368 
1369  // Core implementation invoked by iterator_adaptor.
1370  friend class boost::iterator_core_access;
1371  bool equal(const UsdPrimSiblingIterator &other) const {
1372  return base() == other.base() &&
1373  _proxyPrimPath == other._proxyPrimPath &&
1374  _predicate == other._predicate;
1375  }
1376 
1377  void increment() {
1378  base_type &base = base_reference();
1379  if (Usd_MoveToNextSiblingOrParent(base, _proxyPrimPath, _predicate)) {
1380  base = nullptr;
1381  _proxyPrimPath = SdfPath();
1382  }
1383  }
1384 
1385  reference dereference() const {
1386  return UsdPrim(base(), _proxyPrimPath);
1387  }
1388 
1389  SdfPath _proxyPrimPath;
1390  Usd_PrimFlagsPredicate _predicate;
1391 };
1392 
1393 // Typedef iterator range.
1394 typedef boost::iterator_range<UsdPrimSiblingIterator> UsdPrimSiblingRange;
1395 
1396 // Inform TfIterator it should feel free to make copies of the range type.
1397 template <>
1398 struct Tf_ShouldIterateOverCopy<
1399  UsdPrimSiblingRange> : boost::true_type {};
1400 template <>
1401 struct Tf_ShouldIterateOverCopy<
1402  const UsdPrimSiblingRange> : boost::true_type {};
1403 
1404 #endif // doxygen
1405 
1406 
1407 UsdPrimSiblingRange
1408 UsdPrim::GetFilteredChildren(const Usd_PrimFlagsPredicate &pred) const
1409 {
1410  return _MakeSiblingRange(
1411  Usd_CreatePredicateForTraversal(_Prim(), _ProxyPrimPath(), pred));
1412 }
1413 
1414 UsdPrimSiblingRange
1416 {
1418 }
1419 
1420 UsdPrimSiblingRange
1422 {
1424 }
1425 
1426 // Helper to make a sibling range.
1428 UsdPrim::_MakeSiblingRange(const Usd_PrimFlagsPredicate &pred) const {
1429  Usd_PrimDataConstPtr firstChild = get_pointer(_Prim());
1430  SdfPath firstChildPath = _ProxyPrimPath();
1431  if (!Usd_MoveToChild(firstChild, firstChildPath, pred)) {
1432  firstChild = nullptr;
1433  firstChildPath = SdfPath();
1434  }
1435 
1436  return SiblingRange(
1437  SiblingIterator(firstChild, firstChildPath, pred),
1438  SiblingIterator(nullptr, SdfPath(), pred));
1439 }
1440 
1441 #ifdef doxygen
1442 
1446 public:
1452  typedef unspecified-integral-type difference_type;
1454  reference operator*() const;
1456  unspecified-type operator->() const;
1461 private:
1463  friend bool operator==(const UsdPrimSubtreeIterator &lhs,
1464  const UsdPrimSubtreeIterator &rhs);
1466  friend bool operator!=(const UsdPrimSubtreeIterator &lhs,
1467  const UsdPrimSubtreeIterator &rhs);
1468 };
1469 
1475 public:
1481  typedef unspecified-integral-type difference_type;
1486 
1490 
1492  template <class ForwardRange>
1493  UsdPrimSubtreeRange(const ForwardRange &r);
1494 
1496  template <class ForwardRange>
1497  UsdPrimSubtreeRange &operator=(const ForwardRange &r);
1498 
1500  iterator begin() const;
1501 
1503  iterator end() const;
1504 
1506  operator unspecified_bool_type() const;
1507 
1509  bool equal(const iterator_range&) const;
1510 
1512  reference front() const;
1513 
1515  iterator_range& advance_begin(difference_type n);
1516 
1518  iterator_range& advance_end(difference_type n);
1519 
1521  bool empty() const;
1522 
1523 private:
1525  friend bool operator==(const UsdPrimSubtreeRange &lhs,
1526  const UsdPrimSubtreeRange &rhs);
1528  friend bool operator!=(const UsdPrimSubtreeRange &lhs,
1529  const UsdPrimSubtreeRange &rhs);
1530 };
1531 
1532 #else
1533 
1534 // Subtree iterator class. Converts ref to weak and filters according to a
1535 // supplied predicate.
1536 class UsdPrimSubtreeIterator : public boost::iterator_adaptor<
1537  UsdPrimSubtreeIterator, // crtp base.
1538  const Usd_PrimData *, // base iterator.
1539  UsdPrim, // value type.
1540  boost::forward_traversal_tag, // traversal
1541  UsdPrim> // reference type.
1542 {
1543 public:
1544  // Default ctor.
1546 
1547 private:
1548  friend class UsdPrim;
1549 
1550  // Constructor used by Prim.
1551  UsdPrimSubtreeIterator(const base_type &i, const SdfPath &proxyPrimPath,
1552  const Usd_PrimFlagsPredicate &predicate)
1553  : iterator_adaptor_(i)
1554  , _proxyPrimPath(proxyPrimPath)
1555  , _predicate(predicate) {
1556  // Need to advance iterator to first matching element.
1557  base_type &base = base_reference();
1558  if (base && !Usd_EvalPredicate(_predicate, base, _proxyPrimPath)) {
1559  if (Usd_MoveToNextSiblingOrParent(base, _proxyPrimPath,
1560  _predicate)) {
1561  base = nullptr;
1562  _proxyPrimPath = SdfPath();
1563  }
1564  }
1565  }
1566 
1567  // Core implementation invoked by iterator_adaptor.
1568  friend class boost::iterator_core_access;
1569  bool equal(const UsdPrimSubtreeIterator &other) const {
1570  return base() == other.base() &&
1571  _proxyPrimPath == other._proxyPrimPath &&
1572  _predicate == other._predicate;
1573  }
1574 
1575  void increment() {
1576  base_type &base = base_reference();
1577  if (!Usd_MoveToChild(base, _proxyPrimPath, _predicate)) {
1578  while (Usd_MoveToNextSiblingOrParent(base, _proxyPrimPath,
1579  _predicate)) {}
1580  }
1581  }
1582 
1583  reference dereference() const {
1584  return UsdPrim(base(), _proxyPrimPath);
1585  }
1586 
1587  SdfPath _proxyPrimPath;
1588  Usd_PrimFlagsPredicate _predicate;
1589 };
1590 
1591 // Typedef iterator range.
1592 typedef boost::iterator_range<UsdPrimSubtreeIterator> UsdPrimSubtreeRange;
1593 
1594 // Inform TfIterator it should feel free to make copies of the range type.
1595 template <>
1596 struct Tf_ShouldIterateOverCopy<
1597  UsdPrimSubtreeRange> : boost::true_type {};
1598 template <>
1599 struct Tf_ShouldIterateOverCopy<
1600  const UsdPrimSubtreeRange> : boost::true_type {};
1601 
1602 #endif // doxygen
1603 
1604 UsdPrimSubtreeRange
1605 UsdPrim::GetFilteredDescendants(const Usd_PrimFlagsPredicate &pred) const
1606 {
1607  return _MakeDescendantsRange(
1608  Usd_CreatePredicateForTraversal(_Prim(), _ProxyPrimPath(), pred));
1609 }
1610 
1611 UsdPrimSubtreeRange
1613 {
1615 }
1616 
1617 UsdPrimSubtreeRange
1619 {
1621 }
1622 
1623 // Helper to make a sibling range.
1625 UsdPrim::_MakeDescendantsRange(const Usd_PrimFlagsPredicate &pred) const {
1626  Usd_PrimDataConstPtr firstChild = get_pointer(_Prim());
1627  SdfPath firstChildPath = _ProxyPrimPath();
1628  Usd_PrimDataConstPtr endChild = firstChild;
1629  SdfPath endChildPath = firstChildPath;
1630  if (Usd_MoveToChild(firstChild, firstChildPath, pred)) {
1631  while (Usd_MoveToNextSiblingOrParent(endChild, endChildPath, pred)) {}
1632  }
1633 
1634  return SubtreeRange(
1635  SubtreeIterator(firstChild, firstChildPath, pred),
1636  SubtreeIterator(endChild, endChildPath, pred));
1637 }
1638 
1639 
1641 // UsdObject methods that require UsdPrim be a complete type.
1642 
1643 inline UsdPrim
1645 {
1646  return UsdPrim(_prim, _proxyPrimPath);
1647 }
1648 
1649 PXR_NAMESPACE_CLOSE_SCOPE
1650 
1651 #endif // USD_PRIM_H
1652 
USD_API UsdPrim GetMaster() const
If this prim is an instance, return the UsdPrim for the corresponding master.
USD_API SdfPathVector FindAllAttributeConnectionPaths(std::function< bool(UsdAttribute const &)> const &pred=nullptr, bool recurseOnSources=false) const
Search the prim subtree rooted at this prim for attributes for which predicate returns true...
UsdPrim GetPrimInMaster() const
If this prim is an instance proxy, return the UsdPrim for the corresponding prim in the instance&#39;s ma...
Definition: prim.h:1117
USD_API bool HasAuthoredPayloads() const
Return true if this prim has any authored payloads.
bool IsInMaster() const
Return true if this prim is located in a subtree of prims rooted at a master prim, false otherwise.
Definition: prim.h:1104
A proxy class for applying listOp edits to the specializes list for a prim.
Definition: specializes.h:51
USD_API UsdAttribute CreateAttribute(const TfToken &name, const SdfValueTypeName &typeName, bool custom, SdfVariability variability=SdfVariabilityVarying) const
Author scene description for the attribute named attrName at the current EditTarget if none already e...
USD_API TfTokenVector GetPropertyOrder() const
Return the strongest propertyOrder metadata value authored on this prim.
SdfSpecifier GetSpecifier() const
Return this prim&#39;s composed specifier.
Definition: prim.h:151
iterator::value_type value_type
Iterator value_type.
Definition: prim.h:1483
USD_API void SetPropertyOrder(const TfTokenVector &order) const
Author an opinion for propertyOrder metadata on this prim at the current EditTarget.
SiblingRange GetAllChildren() const
Return all this prim&#39;s children as an iterable range.
Definition: prim.h:1415
USD_API UsdPayloads GetPayloads() const
Return a UsdPayloads object that allows one to add, remove, or mutate payloads at the currently set U...
unspecified integral type difference_type
Iterator difference type.
Definition: prim.h:1452
UsdObjType
Enum values to represent the various Usd object types.
Definition: object.h:48
USD_API bool IsPseudoRoot() const
Returns true if the prim is the pseudo root.
USD_API TfTokenVector GetAuthoredPropertyNames(const PropertyPredicateFunc &predicate={}) const
Return this prim&#39;s property names (attributes and relationships) that have authored scene description...
bool HasAuthoredInstanceable() const
Return true if this prim has an authored opinion for &#39;instanceable&#39;, false otherwise.
Definition: prim.h:1078
USD_API bool HasVariantSets() const
Return true if this prim has any authored VariantSets.
PcpPrimIndex is an index of the all sites of scene description that contribute opinions to a specific...
Definition: primIndex.h:77
SubtreeRange GetDescendants() const
Return this prim&#39;s active, loaded, defined, non-abstract descendants as an iterable range...
Definition: prim.h:1618
unspecified UsdPrimDefaultPredicate
The default predicate used for prim traversals in methods like UsdPrim::GetChildren, UsdStage::Traverse, and by UsdPrimRange.
friend bool operator!=(const UsdPrimSubtreeIterator &lhs, const UsdPrimSubtreeIterator &rhs)
Inequality.
bool ClearInstanceable() const
Remove the authored &#39;instanceable&#39; opinion at the current EditTarget.
Definition: prim.h:1072
USD_API UsdRelationship CreateRelationship(const TfToken &relName, bool custom=true) const
Author scene description for the relationship named relName at the current EditTarget if none already...
iterator begin() const
First iterator.
bool IsAbstract() const
Return true if this prim or any of its ancestors is a class.
Definition: prim.h:237
value_type reference
Iterator reference type, in this case the same as value_type.
Definition: prim.h:1450
friend bool operator==(const UsdPrimSiblingIterator &lhs, const UsdPrimSiblingIterator &rhs)
Equality.
reference operator*() const
Dereference.
bool IsA() const
Return true if the UsdPrim is/inherits a Schema of type T.
Definition: prim.h:458
UsdPrimSiblingIterator iterator
Iterator type.
Definition: prim.h:1285
bool IsMaster() const
Return true if this prim is a master prim, false otherwise.
Definition: prim.h:1097
friend bool operator!=(const UsdPrimSiblingRange &lhs, const UsdPrimSiblingRange &rhs)
Inequality comparison.
bool IsInstanceProxy() const
Return true if this prim is an instance proxy, false otherwise.
Definition: prim.h:1092
UsdPrim GetParent() const
Return this prim&#39;s parent prim.
Definition: prim.h:644
iterator end() const
Past-the-end iterator.
UsdPrim value_type
Iterator value type.
Definition: prim.h:1256
USD_API UsdVariantSet GetVariantSet(const std::string &variantSetName) const
Retrieve a specifically named VariantSet for editing or constructing a UsdEditTarget.
USD_API std::vector< UsdRelationship > GetAuthoredRelationships() const
Like GetRelationships(), but exclude relationships without authored scene description from the result...
USD_API std::vector< UsdProperty > GetPropertiesInNamespace(const std::vector< std::string > &namespaces) const
Return this prim&#39;s properties that are inside the given property namespace ordered according to the s...
bool IsModel() const
Return true if this prim is a model based on its kind metadata, false otherwise.
Definition: prim.h:229
USD_API UsdRelationship GetRelationship(const TfToken &relName) const
Return a UsdRelationship with the name relName.
USD_API TfTokenVector GetAppliedSchemas() const
Return a vector containing the names of API schemas which have been applied to this prim...
friend bool operator!=(const UsdPrimSiblingIterator &lhs, const UsdPrimSiblingIterator &rhs)
Inequality.
#define TF_CODING_ERROR(fmt, args)
Issue an internal programming error, but continue execution.
Definition: diagnostic.h:87
bool ClearTypeName() const
Clear the opinion for this Prim&#39;s typeName at the current edit target.
Definition: prim.h:182
bool HasDefiningSpecifier() const
Return true if this prim has a specifier of type SdfSpecifierDef or SdfSpecifierClass.
Definition: prim.h:245
USD_API bool ClearMetadata(const TfToken &key) const
Clears the authored key&#39;s value at the current EditTarget, returning false on error.
USD_API bool HasAttribute(const TfToken &attrName) const
Return true if this prim has an attribute named attrName, false otherwise.
The outermost container for scene description, which owns and presents composed prims as a scenegraph...
Definition: stage.h:142
reference front() const
Return *begin(). This range must not be empty.
friend bool operator==(const UsdPrimSiblingRange &lhs, const UsdPrimSiblingRange &rhs)
Equality comparison.
Represents a value type name, i.e.
Definition: valueTypeName.h:83
Load a prim plus all its descendants.
Definition: common.h:140
A proxy class for applying listOp edits to the inherit paths list for a prim.
Definition: inherits.h:51
friend bool operator!=(const UsdPrimSubtreeRange &lhs, const UsdPrimSubtreeRange &rhs)
Inequality comparison.
UsdPrimSiblingIterator & operator++()
Postincrement.
bool GetMetadata(const TfToken &key, T *value) const
Resolve the requested metadatum named key into value, returning true on success.
Definition: object.h:742
unspecified integral type difference_type
Iterator difference type.
Definition: prim.h:1289
The base class for all API schemas.
Scenegraph object for authoring and retrieving numeric, string, and array valued data, sampled over time.
Definition: attribute.h:176
USD_API bool HasAuthoredReferences() const
Return true if this prim has any authored references.
USD_API bool RemoveProperty(const TfToken &propName)
Remove all scene description for the property with the given propName in the current UsdEditTarget...
Forward iterator range of sibling UsdPrim s.
Definition: prim.h:1282
USD_API void Load(UsdLoadPolicy policy=UsdLoadWithDescendants) const
Load this prim, all its ancestors, and by default all its descendants.
UsdReferences provides an interface to authoring and introspecting references in Usd.
Definition: references.h:214
UsdPrimSubtreeIterator iterator
Iterator type.
Definition: prim.h:1477
iterator::value_type value_type
Iterator value_type.
Definition: prim.h:1291
bool HasAuthoredActive() const
Return true if this prim has an authored opinion for &#39;active&#39;, false otherwise.
Definition: prim.h:218
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:89
SiblingRange GetFilteredChildren(const Usd_PrimFlagsPredicate &predicate) const
Return a subset of all of this prim&#39;s children filtered by predicate as an iterable range...
Definition: prim.h:1408
USD_API bool HasPayload() const
bool SetMetadata(const TfToken &key, const T &value) const
Set metadatum key&#39;s value to value.
Definition: object.h:751
unspecified integral type difference_type
Iterator difference type.
Definition: prim.h:1260
SdfSpecifier
An enum that identifies the possible specifiers for an SdfPrimSpec.
Definition: types.h:123
iterator_range & advance_end(difference_type n)
Advance this range&#39;s end iterator.
USD_API UsdPrim GetChild(const TfToken &name) const
Return this prim&#39;s direct child named name if it has one, otherwise return an invalid UsdPrim...
UsdPrimSiblingRange(UsdPrimSiblingIterator begin, UsdPrimSiblingIterator end)
Construct with a pair of iterators.
USD_API std::vector< UsdAttribute > GetAttributes() const
Like GetProperties(), but exclude all relationships from the result.
USD_API UsdPrim GetNextSibling() const
Return this prim&#39;s next active, loaded, defined, non-abstract sibling if it has one, otherwise return an invalid UsdPrim.
USD_API std::vector< UsdRelationship > GetRelationships() const
Like GetProperties(), but exclude all attributes from the result.
UsdPrimSubtreeIterator & operator++()
Postincrement.
USD_API SdfPrimSpecHandleVector GetPrimStack() const
Return a list of PrimSpecs that provide opinions for this prim (i.e.
bool SetSpecifier(SdfSpecifier specifier) const
Author an opinion for this Prim&#39;s specifier at the current edit target.
Definition: prim.h:167
static TF_API std::string GetCanonicalTypeName(const std::type_info &)
Return the canonical typeName used for a given std::type_info.
USD_API std::vector< UsdProperty > GetAuthoredProperties(const PropertyPredicateFunc &predicate={}) const
Return this prim&#39;s properties (attributes and relationships) that have authored scene description...
A UsdVariantSet represents a single VariantSet in USD (e.g.
Definition: variantSets.h:56
Multiple Apply API Schema.
bool SetTypeName(const TfToken &typeName) const
Author this Prim&#39;s typeName at the current EditTarget.
Definition: prim.h:176
USD_API SdfPrimSpecHandle GetPrimDefinition() const
Return this prim&#39;s definition from the UsdSchemaRegistry based on the prim&#39;s type if one exists...
UsdPrim GetPrim() const
Return this object if it is a prim, otherwise return this object&#39;s nearest owning prim...
Definition: prim.h:1644
Forward iterator range of sibling UsdPrim s.
Definition: prim.h:1474
const TfToken & GetTypeName() const
Return this prim&#39;s composed type name.
Definition: prim.h:173
Base class for Usd scenegraph objects, providing common API.
Definition: object.h:129
USD_API std::vector< UsdAttribute > GetAuthoredAttributes() const
Like GetAttributes(), but exclude attributes without authored scene description from the result...
Represents a payload and all its meta data.
Definition: payload.h:59
bool empty() const
Return begin() == end().
SdfVariability
An enum that identifies variability types for attributes.
Definition: types.h:182
UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a &quot;Prim&quot; as ...
Definition: prim.h:131
UsdPrimSiblingRange & operator=(const ForwardRange &r)
Assign from another compatible range type.
UsdPrim value_type
Iterator value type.
Definition: prim.h:1448
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:438
Single Apply API schema.
friend bool operator==(const UsdPrimSubtreeRange &lhs, const UsdPrimSubtreeRange &rhs)
Equality comparison.
UsdPrimSubtreeRange & operator=(const ForwardRange &r)
Assign from another compatible range type.
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:287
bool HasAuthoredTypeName() const
Return true if a typeName has been authored.
Definition: prim.h:187
bool IsActive() const
Return true if this prim is active, meaning neither it nor any of its ancestors have active=false...
Definition: prim.h:195
iterator_range & advance_begin(difference_type n)
Advance this range&#39;s begin iterator.
USD_API UsdReferences GetReferences() const
Return a UsdReferences object that allows one to add, remove, or mutate references at the currently s...
iterator::reference reference
Iterator reference_type.
Definition: prim.h:1485
SubtreeRange GetFilteredDescendants(const Usd_PrimFlagsPredicate &predicate) const
Return a subset of all of this prim&#39;s descendants filtered by predicate as an iterable range...
Definition: prim.h:1605
UsdPayloads provides an interface to authoring and introspecting payloads.
Definition: payloads.h:43
A UsdRelationship creates dependencies between scenegraph objects by allowing a prim to target other ...
Definition: relationship.h:128
USD_API PcpPrimIndex ComputeExpandedPrimIndex() const
Compute the prim index containing all sites that could contribute opinions to this prim...
USD_API TfTokenVector GetPropertyNames(const PropertyPredicateFunc &predicate={}) const
Return all of this prim&#39;s property names (attributes and relationships), including all builtin proper...
USD_API bool SetPayload(const SdfPayload &payload) const
iterator begin() const
First iterator.
bool SetActive(bool active) const
Author &#39;active&#39; metadata for this prim at the current EditTarget.
Definition: prim.h:201
bool IsDefined() const
Return true if this prim and all its ancestors have defining specifiers, false otherwise.
Definition: prim.h:241
friend bool operator==(const UsdPrimSubtreeIterator &lhs, const UsdPrimSubtreeIterator &rhs)
Equality.
UsdLoadPolicy
Controls UsdStage::Load() and UsdPrim::Load() behavior regarding whether or not descendant prims are ...
Definition: common.h:138
USD_API bool HasAuthoredMetadata(const TfToken &key) const
Returns true if the key has an authored value, false if no value was authored or the only value avail...
Base class for UsdAttribute and UsdRelationship scenegraph objects.
Definition: property.h:55
bool IsLoaded() const
Return true if this prim is active, and either it is loadable and it is loaded, or its nearest loadab...
Definition: prim.h:225
USD_API bool HasAuthoredInherits() const
Return true if this prim has any authored inherits.
An forward-iterable range that traverses a subtree of prims rooted at a given prim in depth-first ord...
Definition: primRange.h:118
reference operator*() const
Dereference.
unspecified integral type difference_type
Iterator difference type.
Definition: prim.h:1481
USD_API UsdVariantSets GetVariantSets() const
Return a UsdVariantSets object representing all the VariantSets present on this prim.
bool IsInstance() const
Return true if this prim is an instance of a master, false otherwise.
Definition: prim.h:1087
unspecified type operator->() const
Indirection.
USD_API bool HasRelationship(const TfToken &relName) const
Return true if this prim has a relationship named relName, false otherwise.
Forward traversal iterator of sibling UsdPrim s.
Definition: prim.h:1445
unspecified UsdPrimAllPrimsPredicate
Predicate that includes all prims.
UsdPrim()
Construct an invalid prim.
Definition: prim.h:143
std::function< bool(const TfToken &propertyName)> PropertyPredicateFunc
Alias for the &quot;predicate&quot; function parameter passed into the various Get{Authored}{PropertyNames,Properties} methods.
Definition: prim.h:258
USD_API SdfPathVector FindAllRelationshipTargetPaths(std::function< bool(UsdRelationship const &)> const &pred=nullptr, bool recurseOnTargets=false) const
Search the prim subtree rooted at this prim for relationships for which predicate returns true...
TfType represents a dynamic runtime type.
Definition: type.h:70
UsdPrimSubtreeIterator SubtreeIterator
Convenience typedefs.
Definition: prim.h:139
reference front() const
Return *begin(). This range must not be empty.
USD_API bool HasProperty(const TfToken &propName) const
Return true if this prim has an property named propName, false otherwise.
USD_API UsdSpecializes GetSpecializes() const
Return a UsdSpecializes object that allows one to add, remove, or mutate specializes at the currently...
bool equal(const iterator_range &) const
Equality compare.
USD_API UsdAttribute GetAttribute(const TfToken &attrName) const
Return a UsdAttribute with the name attrName.
UsdPrimSiblingIterator SiblingIterator
Convenience typedefs.
Definition: prim.h:135
USD_API std::vector< UsdProperty > GetProperties(const PropertyPredicateFunc &predicate={}) const
Return all of this prim&#39;s properties (attributes and relationships), including all builtin properties...
USD_API void Unload() const
Unloads this prim and all its descendants.
UsdPrimSiblingIterator const_iterator
Const iterator type.
Definition: prim.h:1287
USD_API std::vector< UsdProperty > GetAuthoredPropertiesInNamespace(const std::vector< std::string > &namespaces) const
Like GetPropertiesInNamespace(), but exclude properties that do not have authored scene description f...
bool empty() const
Return begin() == end().
UsdVariantSets represents the collection of VariantSets that are present on a UsdPrim.
Definition: variantSets.h:211
USD_API bool ClearPayload() const
bool SetInstanceable(bool instanceable) const
Author &#39;instanceable&#39; metadata for this prim at the current EditTarget.
Definition: prim.h:1066
UsdPrimSubtreeIterator const_iterator
Const iterator type.
Definition: prim.h:1479
The base class for all schema types in Usd.
Definition: schemaBase.h:56
SiblingRange GetChildren() const
Return this prim&#39;s active, loaded, defined, non-abstract children as an iterable range.
Definition: prim.h:1421
iterator::reference reference
Iterator reference_type.
Definition: prim.h:1293
USD_API UsdInherits GetInherits() const
Return a UsdInherits object that allows one to add, remove, or mutate inherits at the currently set U...
unspecified type operator->() const
Indirection.
Forward traversal iterator of sibling UsdPrim s.
Definition: prim.h:1253
iterator end() const
Past-the-end iterator.
bool equal(const iterator_range &) const
Equality compare.
SubtreeRange GetAllDescendants() const
Return all this prim&#39;s descendants as an iterable range.
Definition: prim.h:1612
USD_API bool HasAuthoredSpecializes() const
Returns true if this prim has any authored specializes.
iterator_range & advance_end(difference_type n)
Advance this range&#39;s end iterator.
USD_API UsdProperty GetProperty(const TfToken &propName) const
Return a UsdProperty with the name propName.
bool IsGroup() const
Return true if this prim is a model group based on its kind metadata, false otherwise.
Definition: prim.h:234
UsdPrimSubtreeRange(UsdPrimSubtreeIterator begin, UsdPrimSubtreeIterator end)
Construct with a pair of iterators.
const PcpPrimIndex & GetPrimIndex() const
Return the cached prim index containing all sites that contribute opinions to this prim...
Definition: prim.h:1153
bool ClearActive() const
Remove the authored &#39;active&#39; opinion at the current EditTarget.
Definition: prim.h:210
value_type reference
Iterator reference type, in this case the same as value_type.
Definition: prim.h:1258
bool HasAPI(const TfToken &instanceName=TfToken()) const
Return true if the UsdPrim has had an API schema represented by the C++ class type T applied to it th...
Definition: prim.h:506
bool IsInstanceable() const
Return true if this prim has been marked as instanceable.
Definition: prim.h:1058
iterator_range & advance_begin(difference_type n)
Advance this range&#39;s begin iterator.
USD_API UsdPrim GetFilteredNextSibling(const Usd_PrimFlagsPredicate &predicate) const
Return this prim&#39;s next sibling that matches predicate if it has one, otherwise return the invalid Us...