All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
object.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_OBJECT_H
25 #define PXR_USD_USD_OBJECT_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/primData.h"
33 #include "pxr/usd/usd/stage.h"
34 
35 #include "pxr/usd/sdf/abstractData.h"
36 #include "pxr/usd/sdf/path.h"
37 
38 #include <type_traits>
39 
40 PXR_NAMESPACE_OPEN_SCOPE
41 
42 
44 
50 {
51  // Value order matters in this enum.
52  UsdTypeObject,
53  UsdTypePrim,
54  UsdTypeProperty,
55  UsdTypeAttribute,
56  UsdTypeRelationship,
57 
58  Usd_NumObjTypes
59 };
60 
61 
62 namespace _Detail {
63 
64 // A metafunction that takes a UsdObject class like UsdObject, UsdPrim,
65 // UsdProperty, etc, and gives its corresponding UsdObjType, e.g. UsdTypeObject,
66 // UsdTypePrim, UsdTypeProperty, etc. Usage: GetObjType<UsdPrim>::Value.
67 template <UsdObjType Type>
68 struct Const { static const UsdObjType Value = Type; };
69 template <class T> struct GetObjType {
70  static_assert(std::is_base_of<UsdObject, T>::value,
71  "Type T must be a subclass of UsdObject.");
72 };
73 template <> struct GetObjType<UsdObject> : Const<UsdTypeObject> {};
74 template <> struct GetObjType<UsdPrim> : Const<UsdTypePrim> {};
75 template <> struct GetObjType<UsdProperty> : Const<UsdTypeProperty> {};
76 template <> struct GetObjType<UsdAttribute> : Const<UsdTypeAttribute> {};
77 template <> struct GetObjType<UsdRelationship> : Const<UsdTypeRelationship> {};
78 
79 } // _Detail
80 
83 inline bool
84 UsdIsSubtype(UsdObjType baseType, UsdObjType subType) {
85  return (baseType == UsdTypeObject) || (baseType == subType) ||
86  (baseType == UsdTypeProperty && subType > UsdTypeProperty);
87 }
88 
91 inline bool
93  return UsdIsSubtype(to, from);
94 }
95 
98 inline bool
100  return type == UsdTypePrim ||
101  type == UsdTypeAttribute ||
102  type == UsdTypeRelationship;
103 }
104 
130 class UsdObject {
131 public:
133  UsdObject() : _type(UsdTypeObject) {}
134 
135  // --------------------------------------------------------------------- //
138  // --------------------------------------------------------------------- //
139 
141  bool IsValid() const {
142  if (!UsdIsConcrete(_type) || !_prim)
143  return false;
144  if (_type == UsdTypePrim)
145  return true;
146  SdfSpecType specType = _GetDefiningSpecType();
147  return (_type == UsdTypeAttribute &&
148  specType == SdfSpecTypeAttribute) ||
149  (_type == UsdTypeRelationship &&
150  specType == SdfSpecTypeRelationship);
151  }
152 
154  explicit operator bool() const {
155  return IsValid();
156  }
157 
158 public:
159 
162  friend bool operator==(const UsdObject &lhs, const UsdObject &rhs) {
163  return lhs._type == rhs._type &&
164  lhs._prim == rhs._prim &&
165  lhs._proxyPrimPath == rhs._proxyPrimPath &&
166  lhs._propName == rhs._propName;
167  }
168 
171  friend bool operator!=(const UsdObject &lhs, const UsdObject &rhs) {
172  return !(lhs == rhs);
173  }
174 
178  friend bool operator<(const UsdObject &lhs, const UsdObject &rhs) {
179  return lhs.GetPath() < rhs.GetPath();
180  }
181 
182  // hash_value overload for std/boost hash.
183  USD_API
184  friend size_t hash_value(const UsdObject &obj);
185 
188  USD_API
189  UsdStageWeakPtr GetStage() const;
190 
194  SdfPath GetPath() const {
195  // Allow getting expired object paths.
196  if (!_proxyPrimPath.IsEmpty()) {
197  return _type == UsdTypePrim ?
198  _proxyPrimPath : _proxyPrimPath.AppendProperty(_propName);
199  }
200  else if (Usd_PrimDataConstPtr p = get_pointer(_prim)) {
201  return _type == UsdTypePrim ?
202  p->GetPath() : p->GetPath().AppendProperty(_propName);
203  }
204  return SdfPath();
205  }
206 
209  const SdfPath &GetPrimPath() const {
210  // Allow getting expired object paths.
211  if (!_proxyPrimPath.IsEmpty()) {
212  return _proxyPrimPath;
213  }
214  else if (Usd_PrimDataConstPtr p = get_pointer(_prim)) {
215  return p->GetPath();
216  }
217  return SdfPath::EmptyPath();
218  }
219 
222  inline UsdPrim GetPrim() const;
223 
229  const TfToken &GetName() const {
230  return _type == UsdTypePrim ? GetPrimPath().GetNameToken() : _propName;
231  }
232 
236  template <class T>
237  T As() const {
238  // compile-time type assertion provided by invoking Is<T>().
239  return Is<T>() ? T(_type, _prim, _proxyPrimPath, _propName) : T();
240  }
241 
247  template <class T>
248  bool Is() const {
249  static_assert(std::is_base_of<UsdObject, T>::value,
250  "Provided type T must derive from or be UsdObject");
251  return UsdIsConvertible(_type, _Detail::GetObjType<T>::Value);
252  }
253 
259  USD_API
260  std::string GetDescription() const;
261 
262  // --------------------------------------------------------------------- //
264  // --------------------------------------------------------------------- //
265 
266 
267  // --------------------------------------------------------------------- //
270  // --------------------------------------------------------------------- //
271 
286  template<typename T>
287  bool GetMetadata(const TfToken& key, T* value) const;
291  USD_API
292  bool GetMetadata(const TfToken& key, VtValue* value) const;
293 
300  template<typename T>
301  bool SetMetadata(const TfToken& key, const T& value) const;
303  USD_API
304  bool SetMetadata(const TfToken& key, const VtValue& value) const;
305 
315  USD_API
316  bool ClearMetadata(const TfToken& key) const;
317 
321  USD_API
322  bool HasMetadata(const TfToken& key) const;
323 
327  USD_API
328  bool HasAuthoredMetadata(const TfToken& key) const;
329 
345  template <class T>
347  const TfToken& key, const TfToken &keyPath, T *value) const;
349  USD_API
351  const TfToken& key, const TfToken &keyPath, VtValue *value) const;
352 
360  template<typename T>
362  const TfToken& key, const TfToken &keyPath, const T& value) const;
364  USD_API
366  const TfToken& key, const TfToken &keyPath, const VtValue& value) const;
367 
375  USD_API
377  const TfToken& key, const TfToken& keyPath) const;
378 
385  USD_API
386  bool HasMetadataDictKey(
387  const TfToken& key, const TfToken &keyPath) const;
388 
395  USD_API
397  const TfToken& key, const TfToken &keyPath) const;
398 
405  USD_API
406  UsdMetadataValueMap GetAllMetadata() const;
407 
414  USD_API
415  UsdMetadataValueMap GetAllAuthoredMetadata() const;
416 
417  // --------------------------------------------------------------------- //
419  // --------------------------------------------------------------------- //
420 
421  // --------------------------------------------------------------------- //
424  // --------------------------------------------------------------------- //
425 
440  USD_API
441  bool IsHidden() const;
442 
445  USD_API
446  bool SetHidden(bool hidden) const;
447 
449  USD_API
450  bool ClearHidden() const;
451 
457  USD_API
458  bool HasAuthoredHidden() const;
459 
478  USD_API
479  VtDictionary GetCustomData() const;
480 
486  USD_API
487  VtValue GetCustomDataByKey(const TfToken &keyPath) const;
488 
491  USD_API
492  void SetCustomData(const VtDictionary &customData) const;
493 
497  USD_API
498  void SetCustomDataByKey(const TfToken &keyPath, const VtValue &value) const;
499 
503  USD_API
504  void ClearCustomData() const;
505 
510  USD_API
511  void ClearCustomDataByKey(const TfToken &keyPath) const;
512 
515  USD_API
516  bool HasCustomData() const;
517 
522  USD_API
523  bool HasCustomDataKey(const TfToken &keyPath) const;
524 
527  USD_API
528  bool HasAuthoredCustomData() const;
529 
534  USD_API
535  bool HasAuthoredCustomDataKey(const TfToken &keyPath) const;
536 
550  USD_API
551  VtDictionary GetAssetInfo() const;
552 
558  USD_API
559  VtValue GetAssetInfoByKey(const TfToken &keyPath) const;
560 
563  USD_API
564  void SetAssetInfo(const VtDictionary &customData) const;
565 
569  USD_API
570  void SetAssetInfoByKey(const TfToken &keyPath, const VtValue &value) const;
571 
575  USD_API
576  void ClearAssetInfo() const;
577 
582  USD_API
583  void ClearAssetInfoByKey(const TfToken &keyPath) const;
584 
587  USD_API
588  bool HasAssetInfo() const;
589 
594  USD_API
595  bool HasAssetInfoKey(const TfToken &keyPath) const;
596 
599  USD_API
600  bool HasAuthoredAssetInfo() const;
601 
606  USD_API
607  bool HasAuthoredAssetInfoKey(const TfToken &keyPath) const;
608 
612  USD_API
613  std::string GetDocumentation() const;
614 
616  USD_API
617  bool SetDocumentation(const std::string& doc) const;
618 
621  USD_API
622  bool ClearDocumentation() const;
623 
626  USD_API
627  bool HasAuthoredDocumentation() const;
628 
629  // --------------------------------------------------------------------- //
631  // --------------------------------------------------------------------- //
632 
633  // XXX: This method can and probably should move to UsdProperty
634  static char GetNamespaceDelimiter()
635  { return SdfPathTokens->namespaceDelimiter.GetText()[0]; }
636 
637 private:
638  template <class T>
639  bool _GetMetadataImpl(const TfToken& key,
640  T* value,
641  const TfToken &keyPath=TfToken()) const;
642 
643  bool _GetMetadataImpl(const TfToken& key,
644  VtValue* value,
645  const TfToken &keyPath=TfToken()) const;
646 
647  template <class T>
648  bool _SetMetadataImpl(const TfToken& key,
649  const T& value,
650  const TfToken &keyPath=TfToken()) const;
651 
652  bool _SetMetadataImpl(const TfToken& key,
653  const VtValue& value,
654  const TfToken &keyPath=TfToken()) const;
655 
656 protected:
657  template <class Derived> struct _Null {};
658 
659  // Private constructor for null dervied types.
660  template <class Derived>
661  explicit UsdObject(_Null<Derived>)
662  : _type(_Detail::GetObjType<Derived>::Value) {}
663 
664  // Private constructor for UsdPrim.
665  UsdObject(const Usd_PrimDataHandle &prim,
666  const SdfPath &proxyPrimPath)
667  : _type(UsdTypePrim)
668  , _prim(prim)
669  , _proxyPrimPath(proxyPrimPath)
670  {
671  TF_VERIFY(!_prim || _prim->GetPath() != _proxyPrimPath);
672  }
673 
674  // Private constructor for UsdAttribute/UsdRelationship.
675  UsdObject(UsdObjType objType,
676  const Usd_PrimDataHandle &prim,
677  const SdfPath &proxyPrimPath,
678  const TfToken &propName)
679  : _type(objType)
680  , _prim(prim)
681  , _proxyPrimPath(proxyPrimPath)
682  , _propName(propName)
683  {
684  TF_VERIFY(!_prim || _prim->GetPath() != _proxyPrimPath);
685  }
686 
687  // Return the stage this object belongs to.
688  UsdStage *_GetStage() const { return _prim->GetStage(); }
689 
690  // Return this object's defining spec type.
691  USD_API
692  SdfSpecType _GetDefiningSpecType() const;
693 
694  // Helper for subclasses: return held prim data.
695  const Usd_PrimDataHandle &_Prim() const { return _prim; }
696 
697  // Helper for subclasses: return held property name.
698  const TfToken &_PropName() const { return _propName; }
699 
700  // Helper for subclasses: return held proxy prim path.
701  const SdfPath &_ProxyPrimPath() const { return _proxyPrimPath; }
702 
703 private:
704  // Helper for the above helper, and also for GetDescription()
705  std::string _GetObjectDescription(const std::string &preface) const;
706 
707  friend class UsdStage;
708 
709  friend UsdObjType Usd_GetObjType(const UsdObject &obj) {
710  return obj._type;
711  }
712 
713  UsdObjType _type;
714  Usd_PrimDataHandle _prim;
715  SdfPath _proxyPrimPath;
716  TfToken _propName;
717 
718 };
719 
720 template<typename T>
721 inline
722 bool
723 UsdObject::GetMetadata(const TfToken& key, T* value) const
724 {
725  return _GetMetadataImpl(key, value);
726 }
727 
728 template<typename T>
729 inline
730 bool
731 UsdObject::SetMetadata(const TfToken& key, const T& value) const
732 {
733  return _SetMetadataImpl(key, value);
734 }
735 
736 template <typename T>
737 inline
738 bool
740  const TfToken &keyPath,
741  T *value) const
742 {
743  return _GetMetadataImpl(key, value, keyPath);
744 }
745 
746 template <typename T>
747 inline
748 bool
750  const TfToken &keyPath,
751  const T& value) const
752 {
753  return _SetMetadataImpl(key, value, keyPath);
754 }
755 
756 template <class T>
757 bool
758 UsdObject::_GetMetadataImpl(const TfToken& key,
759  T* value,
760  const TfToken &keyPath) const
761 {
762  return _GetStage()->_GetMetadata(
763  *this, key, keyPath, /*useFallbacks=*/true, value);
764 }
765 
766 template <class T>
767 bool
768 UsdObject::_SetMetadataImpl(const TfToken& key,
769  const T& value,
770  const TfToken &keyPath) const
771 {
772  return _GetStage()->_SetMetadata(*this, key, keyPath, value);
773 }
774 
775 PXR_NAMESPACE_CLOSE_SCOPE
776 
777 #endif //PXR_USD_USD_OBJECT_H
USD_API UsdStageWeakPtr GetStage() const
Return the stage that owns the object, and to whose state and lifetime this object&#39;s validity is tied...
UsdObjType
Enum values to represent the various Usd object types.
Definition: object.h:49
SDF_API SdfPath AppendProperty(TfToken const &propName) const
Creates a path by appending an element for propName to this path.
USD_API void ClearAssetInfoByKey(const TfToken &keyPath) const
Clear the authored opinion identified by keyPath in this object&#39;s assetInfo dictionary at the current...
T As() const
Convert this UsdObject to another object type T if possible.
Definition: object.h:237
#define TF_DECLARE_WEAK_PTRS(type)
Define standard weak pointer types.
Definition: declarePtrs.h:62
USD_API bool HasAuthoredDocumentation() const
Returns true if documentation was explicitly authored and GetMetadata() will return a meaningful valu...
USD_API VtDictionary GetAssetInfo() const
Return this object&#39;s composed assetInfo dictionary.
USD_API bool HasAssetInfoKey(const TfToken &keyPath) const
Return true if there are any authored or fallback opinions for the element identified by keyPath in t...
bool IsValid() const
Return true if this is a valid object, false otherwise.
Definition: object.h:141
USD_API void SetAssetInfoByKey(const TfToken &keyPath, const VtValue &value) const
Author the element identified by keyPath in this object&#39;s assetInfo dictionary at the current EditTar...
USD_API bool SetHidden(bool hidden) const
Sets the value of the &#39;hidden&#39; metadata field.
bool UsdIsSubtype(UsdObjType baseType, UsdObjType subType)
Return true if subType is the same as or a subtype of baseType, false otherwise.
Definition: object.h:84
A map with string keys and VtValue values.
Definition: dictionary.h:63
USD_API void SetCustomDataByKey(const TfToken &keyPath, const VtValue &value) const
Author the element identified by keyPath in this object&#39;s customData dictionary at the current EditTa...
SdfPath GetPath() const
Return the complete scene path to this object on its UsdStage, which may (UsdPrim) or may not (all ot...
Definition: object.h:194
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 HasCustomData() const
Return true if there are any authored or fallback opinions for this object&#39;s customData dictionary...
friend bool operator<(const UsdObject &lhs, const UsdObject &rhs)
Less-than operator.
Definition: object.h:178
The outermost container for scene description, which owns and presents composed prims as a scenegraph...
Definition: stage.h:143
USD_API void ClearCustomDataByKey(const TfToken &keyPath) const
Clear the authored opinion identified by keyPath in this object&#39;s customData dictionary at the curren...
USD_API void SetAssetInfo(const VtDictionary &customData) const
Author this object&#39;s assetInfo dictionary to assetInfo at the current EditTarget. ...
USD_API bool HasMetadata(const TfToken &key) const
Returns true if the key has a meaningful value, that is, if GetMetadata() will provide a value...
SdfSpecType
An enum that specifies the type of an object.
Definition: types.h:91
bool GetMetadata(const TfToken &key, T *value) const
Resolve the requested metadatum named key into value, returning true on success.
Definition: object.h:723
USD_API bool ClearHidden() const
Clears the opinion for &quot;Hidden&quot; at the current EditTarget.
Scenegraph object for authoring and retrieving numeric, string, and array valued data, sampled over time.
Definition: attribute.h:176
SDF_API const TfToken & GetNameToken() const
Returns the name of the prim, property or relational attribute identified by the path, as a token.
bool GetMetadataByDictKey(const TfToken &key, const TfToken &keyPath, T *value) const
Resolve the requested dictionary sub-element keyPath of dictionary-valued metadatum named key into va...
Definition: object.h:739
USD_API void SetCustomData(const VtDictionary &customData) const
Author this object&#39;s customData dictionary to customData at the current EditTarget.
USD_API bool HasCustomDataKey(const TfToken &keyPath) const
Return true if there are any authored or fallback opinions for the element identified by keyPath in t...
bool UsdIsConcrete(UsdObjType type)
Return true if type is a concrete object type, namely one of Prim, Attribute, or Relationship.
Definition: object.h:99
USD_API bool HasAuthoredMetadataDictKey(const TfToken &key, const TfToken &keyPath) const
Return true if there exists any authored opinion (excluding fallbacks) for key and keyPath...
USD_API VtValue GetAssetInfoByKey(const TfToken &keyPath) const
Return the element identified by keyPath in this object&#39;s composed assetInfo dictionary.
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:87
bool SetMetadata(const TfToken &key, const T &value) const
Set metadatum key&#39;s value to value.
Definition: object.h:731
USD_API bool HasAuthoredHidden() const
Returns true if hidden was explicitly authored and GetMetadata() will return a meaningful value for H...
USD_API bool HasAuthoredAssetInfo() const
Return true if there are any authored opinions (excluding fallback) for this object&#39;s assetInfo dicti...
USD_API void ClearCustomData() const
Clear the authored opinion for this object&#39;s customData dictionary at the current EditTarget...
USD_API UsdMetadataValueMap GetAllMetadata() const
Resolve and return all metadata (including both authored and fallback values) on this object...
#define TF_VERIFY(cond, format,...)
Checks a condition and reports an error if it evaluates false.
Definition: diagnostic.h:283
USD_API VtValue GetCustomDataByKey(const TfToken &keyPath) const
Return the element identified by keyPath in this object&#39;s composed customData dictionary.
USD_API UsdMetadataValueMap GetAllAuthoredMetadata() const
Resolve and return all user-authored metadata on this object, sorted lexicographically.
UsdPrim GetPrim() const
Return this object if it is a prim, otherwise return this object&#39;s nearest owning prim...
Definition: prim.h:1694
USD_API bool HasAssetInfo() const
Return true if there are any authored or fallback opinions for this object&#39;s assetInfo dictionary...
bool Is() const
Return true if this object is convertible to T.
Definition: object.h:248
USD_API bool HasAuthoredCustomDataKey(const TfToken &keyPath) const
Return true if there are any authored opinions (excluding fallback) for the element identified by key...
Base class for Usd scenegraph objects, providing common API.
Definition: object.h:130
USD_API bool ClearDocumentation() const
Clears this object&#39;s documentation (metadata) in the current EditTarget (only).
UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a &quot;Prim&quot; as ...
Definition: prim.h:132
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:288
USD_API std::string GetDocumentation() const
Return this object&#39;s documentation (metadata).
A UsdRelationship creates dependencies between scenegraph objects by allowing a prim to target other ...
Definition: relationship.h:128
USD_API bool ClearMetadataByDictKey(const TfToken &key, const TfToken &keyPath) const
Clear any authored value identified by key and keyPath at the current EditTarget. ...
USD_API bool HasAuthoredAssetInfoKey(const TfToken &keyPath) const
Return true if there are any authored opinions (excluding fallback) for the element identified by key...
USD_API bool IsHidden() const
Gets the value of the &#39;hidden&#39; metadata field, false if not authored.
bool UsdIsConvertible(UsdObjType from, UsdObjType to)
Return true if from is convertible to to, false otherwise.
Definition: object.h:92
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
USD_API VtDictionary GetCustomData() const
Return this object&#39;s composed customData dictionary.
UsdObject()
Default constructor produces an invalid object.
Definition: object.h:133
USD_API void ClearAssetInfo() const
Clear the authored opinion for this object&#39;s assetInfo dictionary at the current EditTarget.
const TfToken & GetName() const
Return the full name of this object, i.e.
Definition: object.h:229
friend bool operator==(const UsdObject &lhs, const UsdObject &rhs)
Equality comparison.
Definition: object.h:162
friend bool operator!=(const UsdObject &lhs, const UsdObject &rhs)
Inequality comparison.
Definition: object.h:171
USD_API std::string GetDescription() const
Return a string that provides a brief summary description of the object.
USD_API bool HasAuthoredCustomData() const
Return true if there are any authored opinions (excluding fallback) for this object&#39;s customData dict...
bool SetMetadataByDictKey(const TfToken &key, const TfToken &keyPath, const T &value) const
Author value to the field identified by key and keyPath at the current EditTarget.
Definition: object.h:749
USD_API bool SetDocumentation(const std::string &doc) const
Sets this object&#39;s documentation (metadata). Returns true on success.
const SdfPath & GetPrimPath() const
Return this object&#39;s path if this object is a prim, otherwise this object&#39;s nearest owning prim&#39;s pat...
Definition: object.h:209
bool IsEmpty() const noexcept
Returns true if this is the empty path (SdfPath::EmptyPath()).
Definition: path.h:413
static SDF_API const SdfPath & EmptyPath()
The empty path value, equivalent to SdfPath().
Provides a container which may hold any type, and provides introspection and iteration over array typ...
Definition: value.h:174
USD_API bool HasMetadataDictKey(const TfToken &key, const TfToken &keyPath) const
Return true if there exists any authored or fallback opinion for key and keyPath. ...