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 void ClearCustomDataByKey(const TfToken &keyPath) const
Clear the authored opinion identified by keyPath in this object's customData dictionary at the curren...
bool SetMetadata(const TfToken &key, const T &value) const
Set metadatum key's value to value.
Definition: object.h:731
T As() const
Convert this UsdObject to another object type T if possible.
Definition: object.h:237
UsdObjType
Enum values to represent the various Usd object types.
Definition: object.h:49
USD_API bool SetDocumentation(const std::string &doc) const
Sets this object's documentation (metadata). Returns true on success.
#define TF_DECLARE_WEAK_PTRS(type)
Define standard weak pointer types.
Definition: declarePtrs.h:62
USD_API bool ClearHidden() const
Clears the opinion for "Hidden" at the current EditTarget.
USD_API bool HasCustomData() const
Return true if there are any authored or fallback opinions for this object's customData dictionary,...
USD_API UsdStageWeakPtr GetStage() const
Return the stage that owns the object, and to whose state and lifetime this object's validity is tied...
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 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 bool SetHidden(bool hidden) const
Sets the value of the 'hidden' metadata field.
friend bool operator<(const UsdObject &lhs, const UsdObject &rhs)
Less-than operator.
Definition: object.h:178
USD_API bool ClearDocumentation() const
Clears this object's documentation (metadata) in the current EditTarget (only).
The outermost container for scene description, which owns and presents composed prims as a scenegraph...
Definition: stage.h:147
USD_API bool HasAuthoredCustomData() const
Return true if there are any authored opinions (excluding fallback) for this object's customData dict...
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.
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 void SetAssetInfo(const VtDictionary &customData) const
Author this object's assetInfo dictionary to assetInfo at the current EditTarget.
Scenegraph object for authoring and retrieving numeric, string, and array valued data,...
Definition: attribute.h:176
USD_API void SetCustomDataByKey(const TfToken &keyPath, const VtValue &value) const
Author the element identified by keyPath in this object's customData dictionary at the current EditTa...
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...
USD_API bool ClearMetadataByDictKey(const TfToken &key, const TfToken &keyPath) const
Clear any authored value identified by key and keyPath at the current EditTarget.
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 std::string GetDocumentation() const
Return this object's documentation (metadata).
USD_API void SetAssetInfoByKey(const TfToken &keyPath, const VtValue &value) const
Author the element identified by keyPath in this object's assetInfo dictionary at the current EditTar...
USD_API VtValue GetCustomDataByKey(const TfToken &keyPath) const
Return the element identified by keyPath in this object's composed customData dictionary.
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:87
USD_API bool ClearMetadata(const TfToken &key) const
Clears the authored key's value at the current EditTarget, returning false on error.
USD_API void ClearAssetInfoByKey(const TfToken &keyPath) const
Clear the authored opinion identified by keyPath in this object's assetInfo dictionary at the current...
USD_API VtValue GetAssetInfoByKey(const TfToken &keyPath) const
Return the element identified by keyPath in this object's composed assetInfo dictionary.
USD_API VtDictionary GetAssetInfo() const
Return this object's composed assetInfo dictionary.
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.
#define TF_VERIFY(cond, format,...)
Checks a condition and reports an error if it evaluates false.
Definition: diagnostic.h:283
USD_API void ClearAssetInfo() const
Clear the authored opinion for this object's assetInfo dictionary at the current EditTarget.
USD_API bool IsHidden() const
Gets the value of the 'hidden' metadata field, false if not authored.
Base class for Usd scenegraph objects, providing common API.
Definition: object.h:130
USD_API std::string GetDescription() const
Return a string that provides a brief summary description of the object.
UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a "Prim" as ...
Definition: prim.h:134
USD_API bool HasAuthoredAssetInfo() const
Return true if there are any authored opinions (excluding fallback) for this object's assetInfo dicti...
SDF_API const TfToken & GetNameToken() const
Returns the name of the prim, property or relational attribute identified by the path,...
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:290
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 HasAuthoredCustomDataKey(const TfToken &keyPath) const
Return true if there are any authored opinions (excluding fallback) for the element identified by key...
USD_API VtDictionary GetCustomData() const
Return this object's composed customData dictionary.
A UsdRelationship creates dependencies between scenegraph objects by allowing a prim to target other ...
Definition: relationship.h:128
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,...
USD_API bool HasAssetInfo() const
Return true if there are any authored or fallback opinions for this object's assetInfo dictionary,...
bool UsdIsConvertible(UsdObjType from, UsdObjType to)
Return true if from is convertible to to, false otherwise.
Definition: object.h:92
Base class for UsdAttribute and UsdRelationship scenegraph objects.
Definition: property.h:55
SdfSpecType
An enum that specifies the type of an object.
Definition: types.h:90
USD_API UsdMetadataValueMap GetAllMetadata() const
Resolve and return all metadata (including both authored and fallback values) on this object,...
const SdfPath & GetPrimPath() const
Return this object's path if this object is a prim, otherwise this object's nearest owning prim's pat...
Definition: object.h:209
const TfToken & GetName() const
Return the full name of this object, i.e.
Definition: object.h:229
UsdObject()
Default constructor produces an invalid object.
Definition: object.h:133
SDF_API SdfPath AppendProperty(TfToken const &propName) const
Creates a path by appending an element for propName to this path.
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 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 HasAuthoredHidden() const
Returns true if hidden was explicitly authored and GetMetadata() will return a meaningful value for H...
USD_API UsdMetadataValueMap GetAllAuthoredMetadata() const
Resolve and return all user-authored metadata on this object, sorted lexicographically.
bool IsValid() const
Return true if this is a valid object, false otherwise.
Definition: object.h:141
USD_API bool HasAuthoredDocumentation() const
Returns true if documentation was explicitly authored and GetMetadata() will return a meaningful valu...
bool IsEmpty() const noexcept
Returns true if this is the empty path (SdfPath::EmptyPath()).
Definition: path.h:419
static SDF_API const SdfPath & EmptyPath()
The empty path value, equivalent to SdfPath().
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 ClearCustomData() const
Clear the authored opinion for this object's customData dictionary at the current EditTarget.
UsdPrim GetPrim() const
Return this object if it is a prim, otherwise return this object's nearest owning prim.
Definition: prim.h:2173
Provides a container which may hold any type, and provides introspection and iteration over array typ...
Definition: value.h:166
USD_API void SetCustomData(const VtDictionary &customData) const
Author this object's customData dictionary to customData at the current EditTarget.
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...
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
bool Is() const
Return true if this object is convertible to T.
Definition: object.h:248