HDK
 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 terms set forth in the LICENSE.txt file available at
5 // https://openusd.org/license.
6 //
7 #ifndef PXR_USD_USD_OBJECT_H
8 #define PXR_USD_USD_OBJECT_H
9 
10 /// \file usd/object.h
11 
12 #include "pxr/pxr.h"
13 #include "pxr/usd/usd/api.h"
14 #include "pxr/usd/usd/common.h"
15 #include "pxr/usd/usd/primData.h"
16 #include "pxr/usd/usd/stage.h"
17 
19 #include "pxr/usd/sdf/path.h"
20 
21 #include "pxr/base/tf/hash.h"
22 
23 #include <type_traits>
24 
26 
27 
29 
30 /// \enum UsdObjType
31 ///
32 /// Enum values to represent the various Usd object types.
33 ///
35 {
36  // Value order matters in this enum.
42 
44 };
45 
46 
47 namespace _Detail {
48 
49 // A metafunction that takes a UsdObject class like UsdObject, UsdPrim,
50 // UsdProperty, etc, and gives its corresponding UsdObjType, e.g. UsdTypeObject,
51 // UsdTypePrim, UsdTypeProperty, etc. Usage: GetObjType<UsdPrim>::Value.
52 template <UsdObjType Type>
53 struct Const { static const UsdObjType Value = Type; };
54 template <class T> struct GetObjType {
56  "Type T must be a subclass of UsdObject.");
57 };
58 template <> struct GetObjType<UsdObject> : Const<UsdTypeObject> {};
59 template <> struct GetObjType<UsdPrim> : Const<UsdTypePrim> {};
60 template <> struct GetObjType<UsdProperty> : Const<UsdTypeProperty> {};
61 template <> struct GetObjType<UsdAttribute> : Const<UsdTypeAttribute> {};
62 template <> struct GetObjType<UsdRelationship> : Const<UsdTypeRelationship> {};
63 
64 } // _Detail
65 
66 /// Return true if \a subType is the same as or a subtype of \a baseType, false
67 /// otherwise.
68 inline bool
69 UsdIsSubtype(UsdObjType baseType, UsdObjType subType) {
70  return (baseType == UsdTypeObject) || (baseType == subType) ||
71  (baseType == UsdTypeProperty && subType > UsdTypeProperty);
72 }
73 
74 /// Return true if \a from is convertible to \a to, false otherwise. Equivalent
75 /// to UsdIsSubtype(to, from).
76 inline bool
78  return UsdIsSubtype(to, from);
79 }
80 
81 /// Return true if \a type is a concrete object type, namely one of Prim,
82 /// Attribute, or Relationship.
83 inline bool
85  return type == UsdTypePrim ||
86  type == UsdTypeAttribute ||
87  type == UsdTypeRelationship;
88 }
89 
90 /// \class UsdObject
91 ///
92 /// Base class for Usd scenegraph objects, providing common API.
93 ///
94 /// The commonality between the three types of scenegraph objects in Usd
95 /// (\ref UsdPrim, \ref UsdAttribute, \ref UsdRelationship) is that they can
96 /// all have metadata. Other objects in the API (\ref UsdReferences,
97 /// \ref UsdVariantSets, etc.) simply \em are kinds of metadata.
98 ///
99 /// UsdObject's API primarily provides schema for interacting with the metadata
100 /// common to all the scenegraph objects, as well as generic access to metadata.
101 ///
102 /// section Usd_UsdObject_Lifetime Lifetime Management and Object Validity
103 ///
104 /// Every derived class of UsdObject supports explicit detection of object
105 /// validity through an \em explicit-bool operator, so client code should always
106 /// be able use objects safely, even across edits to the owning UsdStage.
107 /// UsdObject classes also perform some level of validity checking upon every
108 /// use, in order to facilitate debugging of unsafe code, although we reserve
109 /// the right to activate that behavior only in debug builds, if it becomes
110 /// compelling to do so for performance reasons. This per-use checking will
111 /// cause a fatal error upon failing the inline validity check, with an error
112 /// message describing the namespace location of the dereferenced object on its
113 /// owning UsdStage.
114 ///
115 class UsdObject {
116 public:
117  /// Default constructor produces an invalid object.
118  UsdObject() : _type(UsdTypeObject) {}
119 
120  // --------------------------------------------------------------------- //
121  /// \name Structural and Integrity Info about the Object itself
122  /// @{
123  // --------------------------------------------------------------------- //
124 
125  /// Return true if this is a valid object, false otherwise.
126  bool IsValid() const {
127  if (!UsdIsConcrete(_type) || !_prim)
128  return false;
129  if (_type == UsdTypePrim)
130  return true;
131  SdfSpecType specType = _GetDefiningSpecType();
132  return (_type == UsdTypeAttribute &&
133  specType == SdfSpecTypeAttribute) ||
134  (_type == UsdTypeRelationship &&
135  specType == SdfSpecTypeRelationship);
136  }
137 
138  /// Returns \c true if this object is valid, \c false otherwise.
139  explicit operator bool() const {
140  return IsValid();
141  }
142 
143 public:
144 
145  /// Equality comparison. Return true if \a lhs and \a rhs represent the
146  /// same UsdObject, false otherwise.
147  friend bool operator==(const UsdObject &lhs, const UsdObject &rhs) {
148  return lhs._type == rhs._type &&
149  lhs._prim == rhs._prim &&
150  lhs._proxyPrimPath == rhs._proxyPrimPath &&
151  lhs._propName == rhs._propName;
152  }
153 
154  /// Inequality comparison. Return false if \a lhs and \a rhs represent the
155  /// same UsdObject, true otherwise.
156  friend bool operator!=(const UsdObject &lhs, const UsdObject &rhs) {
157  return !(lhs == rhs);
158  }
159 
160  /// Less-than operator. Returns true if \a lhs < \a rhs.
161  ///
162  /// This simply compares the paths of the objects.
163  friend bool operator<(const UsdObject &lhs, const UsdObject &rhs) {
164  return lhs.GetPath() < rhs.GetPath();
165  }
166 
167  // hash_value overload for std/boost hash.
168  friend size_t hash_value(const UsdObject &obj) {
169  return TfHash()(obj);
170  }
171 
172  // TfHash support
173  template <class HashState>
174  friend void TfHashAppend(HashState &h, const UsdObject &obj) {
175  h.Append(obj._type, obj._prim, obj._proxyPrimPath, obj._propName);
176  }
177 
178  /// Return the stage that owns the object, and to whose state and lifetime
179  /// this object's validity is tied.
180  USD_API
181  UsdStageWeakPtr GetStage() const;
182 
183  /// Return the complete scene path to this object on its UsdStage,
184  /// which may (UsdPrim) or may not (all other subclasses) return a
185  /// cached result
186  SdfPath GetPath() const {
187  // Allow getting expired object paths.
188  if (!_proxyPrimPath.IsEmpty()) {
189  return _type == UsdTypePrim ?
190  _proxyPrimPath : _proxyPrimPath.AppendProperty(_propName);
191  }
192  else if (Usd_PrimDataConstPtr p = get_pointer(_prim)) {
193  return _type == UsdTypePrim ?
194  p->GetPath() : p->GetPath().AppendProperty(_propName);
195  }
196  return SdfPath();
197  }
198 
199  /// Return this object's path if this object is a prim, otherwise this
200  /// object's nearest owning prim's path. Equivalent to GetPrim().GetPath().
201  const SdfPath &GetPrimPath() const {
202  // Allow getting expired object paths.
203  if (!_proxyPrimPath.IsEmpty()) {
204  return _proxyPrimPath;
205  }
206  else if (Usd_PrimDataConstPtr p = get_pointer(_prim)) {
207  return p->GetPath();
208  }
209  return SdfPath::EmptyPath();
210  }
211 
212  /// Return this object if it is a prim, otherwise return this object's
213  /// nearest owning prim.
214  inline UsdPrim GetPrim() const;
215 
216  /// Return the full name of this object, i.e. the last component of its
217  /// SdfPath in namespace.
218  ///
219  /// This is equivalent to, but generally cheaper than,
220  /// GetPath().GetNameToken()
221  const TfToken &GetName() const {
222  return _type == UsdTypePrim ? GetPrimPath().GetNameToken() : _propName;
223  }
224 
225  /// Convert this UsdObject to another object type \p T if possible. Return
226  /// an invalid \p T instance if this object's dynamic type is not
227  /// convertible to \p T or if this object is invalid.
228  template <class T>
229  T As() const {
230  // compile-time type assertion provided by invoking Is<T>().
231  return Is<T>() ? T(_type, _prim, _proxyPrimPath, _propName) : T();
232  }
233 
234  /// Return true if this object is convertible to \p T. This is equivalent
235  /// to but cheaper than:
236  /// \code
237  /// bool(obj.As<T>())
238  /// \endcode
239  template <class T>
240  bool Is() const {
242  "Provided type T must derive from or be UsdObject");
244  }
245 
246  /// Return a string that provides a brief summary description of the
247  /// object. This method, along with IsValid()/bool_operator,
248  /// is always safe to call on a possibly-expired object, and the
249  /// description will specify whether the object is valid or expired,
250  /// along with a few other bits of data.
251  USD_API
252  std::string GetDescription() const;
253 
254  // --------------------------------------------------------------------- //
255  /// @}
256  // --------------------------------------------------------------------- //
257 
258 
259  // --------------------------------------------------------------------- //
260  /// \name Generic Metadata Access
261  /// @{
262  // --------------------------------------------------------------------- //
263 
264  /// Resolve the requested metadatum named \p key into \p value,
265  /// returning true on success.
266  ///
267  /// \return false if \p key was not resolvable, or if \p value's
268  /// type \c T differed from that of the resolved metadatum.
269  ///
270  /// \note For any composition-related metadata, as enumerated in
271  /// GetAllMetadata(), this method will return only the strongest
272  /// opinion found, not applying the composition rules used by Pcp
273  /// to process the data. For more processed/composed views of
274  /// composition data, please refer to the specific interface classes,
275  /// such as UsdReferences, UsdInherits, UsdVariantSets, etc.
276  ///
277  /// \sa \ref Usd_OM_Metadata
278  template<typename T>
279  bool GetMetadata(const TfToken& key, T* value) const;
280  /// \overload
281  ///
282  /// Type-erased access
283  USD_API
284  bool GetMetadata(const TfToken& key, VtValue* value) const;
285 
286  /// Set metadatum \p key's value to \p value.
287  ///
288  /// \return false if \p value's type does not match the schema type
289  /// for \p key.
290  ///
291  /// \sa \ref Usd_OM_Metadata
292  template<typename T>
293  bool SetMetadata(const TfToken& key, const T& value) const;
294  /// \overload
295  USD_API
296  bool SetMetadata(const TfToken& key, const VtValue& value) const;
297 
298  /// Clears the authored \a key's value at the current EditTarget,
299  /// returning false on error.
300  ///
301  /// If no value is present, this method is a no-op and returns true. It is
302  /// considered an error to call ClearMetadata when no spec is present for
303  /// this UsdObject, i.e. if the object has no presence in the
304  /// current UsdEditTarget.
305  ///
306  /// \sa \ref Usd_OM_Metadata
307  USD_API
308  bool ClearMetadata(const TfToken& key) const;
309 
310  /// Returns true if the \a key has a meaningful value, that is, if
311  /// GetMetadata() will provide a value, either because it was authored
312  /// or because a prim's metadata fallback will be provided.
313  USD_API
314  bool HasMetadata(const TfToken& key) const;
315 
316  /// Returns true if the \a key has an authored value, false if no
317  /// value was authored or the only value available is a prim's metadata
318  /// fallback.
319  USD_API
320  bool HasAuthoredMetadata(const TfToken& key) const;
321 
322  /// Resolve the requested dictionary sub-element \p keyPath of
323  /// dictionary-valued metadatum named \p key into \p value,
324  /// returning true on success.
325  ///
326  /// If you know you neeed just a small number of elements from a dictionary,
327  /// accessing them element-wise using this method can be much less
328  /// expensive than fetching the entire dictionary with GetMetadata(key).
329  ///
330  /// \return false if \p key was not resolvable, or if \p value's
331  /// type \c T differed from that of the resolved metadatum.
332  ///
333  /// The \p keyPath is a ':'-separated path addressing an element
334  /// in subdictionaries.
335  ///
336  /// \sa \ref Usd_Dictionary_Type
337  template <class T>
339  const TfToken& key, const TfToken &keyPath, T *value) const;
340  /// \overload
341  USD_API
343  const TfToken& key, const TfToken &keyPath, VtValue *value) const;
344 
345  /// Author \p value to the field identified by \p key and \p keyPath
346  /// at the current EditTarget. The \p keyPath is a ':'-separated path
347  /// identifying a value in subdictionaries stored in the metadata field at
348  /// \p key. Return true if the value is authored successfully, false
349  /// otherwise.
350  ///
351  /// \sa \ref Usd_Dictionary_Type
352  template<typename T>
354  const TfToken& key, const TfToken &keyPath, const T& value) const;
355  /// \overload
356  USD_API
358  const TfToken& key, const TfToken &keyPath, const VtValue& value) const;
359 
360  /// Clear any authored value identified by \p key and \p keyPath
361  /// at the current EditTarget. The \p keyPath is a ':'-separated path
362  /// identifying a path in subdictionaries stored in the metadata field at
363  /// \p key. Return true if the value is cleared successfully, false
364  /// otherwise.
365  ///
366  /// \sa \ref Usd_Dictionary_Type
367  USD_API
369  const TfToken& key, const TfToken& keyPath) const;
370 
371  /// Return true if there exists any authored or fallback opinion for
372  /// \p key and \p keyPath. The \p keyPath is a ':'-separated path
373  /// identifying a value in subdictionaries stored in the metadata field at
374  /// \p key.
375  ///
376  /// \sa \ref Usd_Dictionary_Type
377  USD_API
378  bool HasMetadataDictKey(
379  const TfToken& key, const TfToken &keyPath) const;
380 
381  /// Return true if there exists any authored opinion (excluding
382  /// fallbacks) for \p key and \p keyPath. The \p keyPath is a ':'-separated
383  /// path identifying a value in subdictionaries stored in the metadata field
384  /// at \p key.
385  ///
386  /// \sa \ref Usd_Dictionary_Type
387  USD_API
389  const TfToken& key, const TfToken &keyPath) const;
390 
391  /// Resolve and return all metadata (including both authored and
392  /// fallback values) on this object, sorted lexicographically.
393  ///
394  /// \note This method does not return field keys for composition arcs, such
395  /// as references, inherits, payloads, sublayers, variants, or primChildren,
396  /// nor does it return the default value, timeSamples, or spline.
397  USD_API
399 
400  /// Resolve and return all user-authored metadata on this object,
401  /// sorted lexicographically.
402  ///
403  /// \note This method does not return field keys for composition arcs, such
404  /// as references, inherits, payloads, sublayers, variants, or primChildren,
405  /// nor does it return the default value, timeSamples, or spline.
406  USD_API
408 
409  // --------------------------------------------------------------------- //
410  /// @}
411  // --------------------------------------------------------------------- //
412 
413  // --------------------------------------------------------------------- //
414  /// \name Core metadata fields
415  /// @{
416  // --------------------------------------------------------------------- //
417 
418  /// Gets the value of the 'hidden' metadata field, false if not
419  /// authored.
420  ///
421  /// When an object is marked as hidden, it is an indicator to clients who
422  /// generically display objects (such as GUI widgets) that this object
423  /// should not be included, unless explicitly asked for. Although this
424  /// is just a hint and thus up to each application to interpret, we
425  /// use it primarily as a way of simplifying hierarchy displays, by
426  /// hiding \em only the representation of the object itself, \em not its
427  /// subtree, instead "pulling up" everything below it one level in the
428  /// hierarchical nesting.
429  ///
430  /// Note again that this is a hint for UI only - it should not be
431  /// interpreted by any renderer as making a prim invisible to drawing.
432  USD_API
433  bool IsHidden() const;
434 
435  /// Sets the value of the 'hidden' metadata field. See IsHidden()
436  /// for details.
437  USD_API
438  bool SetHidden(bool hidden) const;
439 
440  /// Clears the opinion for "Hidden" at the current EditTarget.
441  USD_API
442  bool ClearHidden() const;
443 
444  /// Returns true if hidden was explicitly authored and GetMetadata()
445  /// will return a meaningful value for Hidden.
446  ///
447  /// Note that IsHidden returns a fallback value (false) when hidden is not
448  /// authored.
449  USD_API
450  bool HasAuthoredHidden() const;
451 
452  /// Return this object's composed customData dictionary.
453  ///
454  /// CustomData is "custom metadata", a place for applications and users
455  /// to put uniform data that is entirely dynamic and subject to no schema
456  /// known to Usd. Unlike metadata like 'hidden', 'displayName' etc,
457  /// which must be declared in code or a data file that is considered part
458  /// of one's Usd distribution (e.g. a plugInfo.json file) to be used,
459  /// customData keys and the datatypes of their corresponding values are
460  /// ad hoc. No validation will ever be performed that values for the
461  /// same key in different layers are of the same type - strongest simply
462  /// wins.
463  ///
464  /// Dictionaries like customData are composed element-wise, and are
465  /// nestable.
466  ///
467  /// There is no means to query a customData field's valuetype other
468  /// than fetching the value and interrogating it.
469  /// \sa GetCustomDataByKey()
470  USD_API
471  VtDictionary GetCustomData() const;
472 
473  /// Return the element identified by \p keyPath in this object's
474  /// composed customData dictionary. The \p keyPath is a ':'-separated path
475  /// identifying a value in subdictionaries. This is in general more
476  /// efficient than composing the entire customData dictionary and then
477  /// pulling out one sub-element.
478  USD_API
479  VtValue GetCustomDataByKey(const TfToken &keyPath) const;
480 
481  /// Author this object's customData dictionary to \p customData at
482  /// the current EditTarget.
483  USD_API
484  void SetCustomData(const VtDictionary &customData) const;
485 
486  /// Author the element identified by \p keyPath in this object's
487  /// customData dictionary at the current EditTarget. The \p keyPath is a
488  /// ':'-separated path identifying a value in subdictionaries.
489  USD_API
490  void SetCustomDataByKey(const TfToken &keyPath, const VtValue &value) const;
491 
492  /// Clear the authored opinion for this object's customData
493  /// dictionary at the current EditTarget. Do nothing if there is no such
494  /// authored opinion.
495  USD_API
496  void ClearCustomData() const;
497 
498  /// Clear the authored opinion identified by \p keyPath in this
499  /// object's customData dictionary at the current EditTarget. The \p
500  /// keyPath is a ':'-separated path identifying a value in subdictionaries.
501  /// Do nothing if there is no such authored opinion.
502  USD_API
503  void ClearCustomDataByKey(const TfToken &keyPath) const;
504 
505  /// Return true if there are any authored or fallback opinions for
506  /// this object's customData dictionary, false otherwise.
507  USD_API
508  bool HasCustomData() const;
509 
510  /// Return true if there are any authored or fallback opinions for
511  /// the element identified by \p keyPath in this object's customData
512  /// dictionary, false otherwise. The \p keyPath is a ':'-separated path
513  /// identifying a value in subdictionaries.
514  USD_API
515  bool HasCustomDataKey(const TfToken &keyPath) const;
516 
517  /// Return true if there are any authored opinions (excluding
518  /// fallback) for this object's customData dictionary, false otherwise.
519  USD_API
520  bool HasAuthoredCustomData() const;
521 
522  /// Return true if there are any authored opinions (excluding
523  /// fallback) for the element identified by \p keyPath in this object's
524  /// customData dictionary, false otherwise. The \p keyPath is a
525  /// ':'-separated path identifying a value in subdictionaries.
526  USD_API
527  bool HasAuthoredCustomDataKey(const TfToken &keyPath) const;
528 
529  /// Return this object's composed assetInfo dictionary.
530  ///
531  /// The asset info dictionary is used to annotate objects representing the
532  /// root-prims of assets (generally organized as models) with various
533  /// data related to asset management. For example, asset name, root layer
534  /// identifier, asset version etc.
535  ///
536  /// The elements of this dictionary are composed element-wise, and are
537  /// nestable.
538  ///
539  /// There is no means to query an assetInfo field's valuetype other
540  /// than fetching the value and interrogating it.
541  /// \sa GetAssetInfoByKey()
542  USD_API
543  VtDictionary GetAssetInfo() const;
544 
545  /// Return the element identified by \p keyPath in this object's
546  /// composed assetInfo dictionary. The \p keyPath is a ':'-separated path
547  /// identifying a value in subdictionaries. This is in general more
548  /// efficient than composing the entire assetInfo dictionary than
549  /// pulling out one sub-element.
550  USD_API
551  VtValue GetAssetInfoByKey(const TfToken &keyPath) const;
552 
553  /// Author this object's assetInfo dictionary to \p assetInfo at
554  /// the current EditTarget.
555  USD_API
556  void SetAssetInfo(const VtDictionary &customData) const;
557 
558  /// Author the element identified by \p keyPath in this object's
559  /// assetInfo dictionary at the current EditTarget. The \p keyPath is a
560  /// ':'-separated path identifying a value in subdictionaries.
561  USD_API
562  void SetAssetInfoByKey(const TfToken &keyPath, const VtValue &value) const;
563 
564  /// Clear the authored opinion for this object's assetInfo
565  /// dictionary at the current EditTarget. Do nothing if there is no such
566  /// authored opinion.
567  USD_API
568  void ClearAssetInfo() const;
569 
570  /// Clear the authored opinion identified by \p keyPath in this
571  /// object's assetInfo dictionary at the current EditTarget. The \p
572  /// keyPath is a ':'-separated path identifying a value in subdictionaries.
573  /// Do nothing if there is no such authored opinion.
574  USD_API
575  void ClearAssetInfoByKey(const TfToken &keyPath) const;
576 
577  /// Return true if there are any authored or fallback opinions for
578  /// this object's assetInfo dictionary, false otherwise.
579  USD_API
580  bool HasAssetInfo() const;
581 
582  /// Return true if there are any authored or fallback opinions for
583  /// the element identified by \p keyPath in this object's assetInfo
584  /// dictionary, false otherwise. The \p keyPath is a ':'-separated path
585  /// identifying a value in subdictionaries.
586  USD_API
587  bool HasAssetInfoKey(const TfToken &keyPath) const;
588 
589  /// Return true if there are any authored opinions (excluding
590  /// fallback) for this object's assetInfo dictionary, false otherwise.
591  USD_API
592  bool HasAuthoredAssetInfo() const;
593 
594  /// Return true if there are any authored opinions (excluding
595  /// fallback) for the element identified by \p keyPath in this object's
596  /// assetInfo dictionary, false otherwise. The \p keyPath is a
597  /// ':'-separated path identifying a value in subdictionaries.
598  USD_API
599  bool HasAuthoredAssetInfoKey(const TfToken &keyPath) const;
600 
601  /// Return this object's documentation (metadata). This returns the
602  /// empty string if no documentation has been set.
603  /// \sa SetDocumentation()
604  USD_API
605  std::string GetDocumentation() const;
606 
607  /// Sets this object's documentation (metadata). Returns true on success.
608  USD_API
609  bool SetDocumentation(const std::string& doc) const;
610 
611  /// Clears this object's documentation (metadata) in the current EditTarget
612  /// (only). Returns true on success.
613  USD_API
614  bool ClearDocumentation() const;
615 
616  /// Returns true if documentation was explicitly authored and GetMetadata()
617  /// will return a meaningful value for documentation.
618  USD_API
619  bool HasAuthoredDocumentation() const;
620 
621  /// Return this object's display name (metadata). This returns the
622  /// empty string if no display name has been set.
623  /// \sa SetDisplayName()
624  USD_API
625  std::string GetDisplayName() const;
626 
627  /// Sets this object's display name (metadata). Returns true on success.
628  ///
629  /// DisplayName is meant to be a descriptive label, not necessarily an
630  /// alternate identifier; therefore there is no restriction on which
631  /// characters can appear in it.
632  USD_API
633  bool SetDisplayName(const std::string& name) const;
634 
635  /// Clears this object's display name (metadata) in the current EditTarget
636  /// (only). Returns true on success.
637  USD_API
638  bool ClearDisplayName() const;
639 
640  /// Returns true if displayName was explicitly authored and GetMetadata()
641  /// will return a meaningful value for displayName.
642  USD_API
643  bool HasAuthoredDisplayName() const;
644 
645  // --------------------------------------------------------------------- //
646  /// @}
647  // --------------------------------------------------------------------- //
648 
649  // XXX: This method can and probably should move to UsdProperty
650  static char GetNamespaceDelimiter()
651  { return SdfPathTokens->namespaceDelimiter.GetText()[0]; }
652 
653 private:
654  template <class T>
655  bool _GetMetadataImpl(const TfToken& key,
656  T* value,
657  const TfToken &keyPath=TfToken()) const;
658 
659  bool _GetMetadataImpl(const TfToken& key,
660  VtValue* value,
661  const TfToken &keyPath=TfToken()) const;
662 
663  template <class T>
664  bool _SetMetadataImpl(const TfToken& key,
665  const T& value,
666  const TfToken &keyPath=TfToken()) const;
667 
668  bool _SetMetadataImpl(const TfToken& key,
669  const VtValue& value,
670  const TfToken &keyPath=TfToken()) const;
671 
672 protected:
673  template <class Derived> struct _Null {};
674 
675  // Private constructor for null dervied types.
676  template <class Derived>
678  : _type(_Detail::GetObjType<Derived>::Value) {}
679 
680  // Private constructor for UsdPrim.
682  const SdfPath &proxyPrimPath)
683  : _type(UsdTypePrim)
684  , _prim(prim)
685  , _proxyPrimPath(proxyPrimPath)
686  {
687  TF_VERIFY(!_prim || _prim->GetPath() != _proxyPrimPath);
688  }
689 
690  // Private constructor for UsdAttribute/UsdRelationship.
692  const Usd_PrimDataHandle &prim,
693  const SdfPath &proxyPrimPath,
694  const TfToken &propName)
695  : _type(objType)
696  , _prim(prim)
697  , _proxyPrimPath(proxyPrimPath)
698  , _propName(propName)
699  {
700  TF_VERIFY(!_prim || _prim->GetPath() != _proxyPrimPath);
701  }
702 
703  // Return the stage this object belongs to.
704  UsdStage *_GetStage() const { return _prim->GetStage(); }
705 
706  // Return this object's defining spec type.
707  USD_API
709 
710  // Helper for subclasses: return held prim data.
711  const Usd_PrimDataHandle &_Prim() const { return _prim; }
712 
713  // Helper for subclasses: return held property name.
714  const TfToken &_PropName() const { return _propName; }
715 
716  // Helper for subclasses: return held proxy prim path.
717  const SdfPath &_ProxyPrimPath() const { return _proxyPrimPath; }
718 
719 private:
720  // Helper for the above helper, and also for GetDescription()
721  std::string _GetObjectDescription(const std::string &preface) const;
722 
723  friend class UsdStage;
724 
725  friend UsdObjType Usd_GetObjType(const UsdObject &obj) {
726  return obj._type;
727  }
728 
729  UsdObjType _type;
730  Usd_PrimDataHandle _prim;
731  SdfPath _proxyPrimPath;
732  TfToken _propName;
733 
734 };
735 
736 template<typename T>
737 inline
738 bool
739 UsdObject::GetMetadata(const TfToken& key, T* value) const
740 {
741  return _GetMetadataImpl(key, value);
742 }
743 
744 template<typename T>
745 inline
746 bool
747 UsdObject::SetMetadata(const TfToken& key, const T& value) const
748 {
749  return _SetMetadataImpl(key, value);
750 }
751 
752 template <typename T>
753 inline
754 bool
756  const TfToken &keyPath,
757  T *value) const
758 {
759  return _GetMetadataImpl(key, value, keyPath);
760 }
761 
762 template <typename T>
763 inline
764 bool
766  const TfToken &keyPath,
767  const T& value) const
768 {
769  return _SetMetadataImpl(key, value, keyPath);
770 }
771 
772 template <class T>
773 bool
774 UsdObject::_GetMetadataImpl(const TfToken& key,
775  T* value,
776  const TfToken &keyPath) const
777 {
778  return _GetStage()->_GetMetadata(
779  *this, key, keyPath, /*useFallbacks=*/true, value);
780 }
781 
782 template <class T>
783 bool
784 UsdObject::_SetMetadataImpl(const TfToken& key,
785  const T& value,
786  const TfToken &keyPath) const
787 {
788  return _GetStage()->_SetMetadata(*this, key, keyPath, value);
789 }
790 
792 
793 #endif //PXR_USD_USD_OBJECT_H
USD_API bool IsHidden() const
USD_API bool ClearDocumentation() const
UsdStage * _GetStage() const
Definition: object.h:704
USD_API void SetAssetInfoByKey(const TfToken &keyPath, const VtValue &value) const
UsdObjType
Definition: object.h:34
USD_API void SetCustomData(const VtDictionary &customData) const
#define USD_API
Definition: api.h:23
USD_API bool SetHidden(bool hidden) const
USD_API bool HasAuthoredAssetInfo() const
USD_API void ClearAssetInfoByKey(const TfToken &keyPath) const
USD_API bool HasAuthoredMetadata(const TfToken &key) const
GLsizei const GLfloat * value
Definition: glcorearb.h:824
USD_API VtValue GetCustomDataByKey(const TfToken &keyPath) const
UsdObject()
Default constructor produces an invalid object.
Definition: object.h:118
USD_API void SetCustomDataByKey(const TfToken &keyPath, const VtValue &value) const
bool UsdIsSubtype(UsdObjType baseType, UsdObjType subType)
Definition: object.h:69
USD_API void ClearCustomData() const
static char GetNamespaceDelimiter()
Definition: object.h:650
friend size_t hash_value(const UsdObject &obj)
Definition: object.h:168
friend bool operator<(const UsdObject &lhs, const UsdObject &rhs)
Definition: object.h:163
bool IsEmpty() const noexcept
Returns true if this is the empty path (SdfPath::EmptyPath()).
Definition: path.h:398
bool SetMetadata(const TfToken &key, const T &value) const
Definition: object.h:747
UsdObject(_Null< Derived >)
Definition: object.h:677
bool GetMetadata(const TfToken &key, T *value) const
Definition: object.h:739
USD_API bool ClearMetadata(const TfToken &key) const
bool GetMetadataByDictKey(const TfToken &key, const TfToken &keyPath, T *value) const
Definition: object.h:755
UsdStagePtr UsdStageWeakPtr
Definition: common.h:38
USD_API bool HasCustomData() const
OutGridT const XformOp bool bool
Y * get_pointer(TfWeakPtrFacade< X, Y > const &p)
Definition: weakPtrFacade.h:63
USD_API bool HasAuthoredHidden() const
const SdfPath & GetPath() const
Definition: primData.h:67
Definition: hash.h:472
bool UsdIsConcrete(UsdObjType type)
Definition: object.h:84
USD_API bool SetDisplayName(const std::string &name) const
static SDF_API const SdfPath & EmptyPath()
The empty path value, equivalent to SdfPath().
USD_API VtDictionary GetCustomData() const
GLint GLint GLsizei GLint GLenum GLenum type
Definition: glcorearb.h:108
Definition: token.h:70
USD_API UsdMetadataValueMap GetAllAuthoredMetadata() const
UsdStage * GetStage() const
Definition: primData.h:71
USD_API VtValue GetAssetInfoByKey(const TfToken &keyPath) const
A generic, discriminated value, whose type may be queried dynamically.
Definition: Value.h:45
USD_API bool HasAuthoredMetadataDictKey(const TfToken &key, const TfToken &keyPath) const
USD_API bool HasMetadata(const TfToken &key) const
USD_API void ClearAssetInfo() const
const SdfPath & GetPrimPath() const
Definition: object.h:201
Definition: prim.h:116
USD_API void SetAssetInfo(const VtDictionary &customData) const
USD_API bool HasCustomDataKey(const TfToken &keyPath) const
USD_API void ClearCustomDataByKey(const TfToken &keyPath) const
const SdfPath & _ProxyPrimPath() const
Definition: object.h:717
USD_API SdfSpecType _GetDefiningSpecType() const
GLuint const GLchar * name
Definition: glcorearb.h:786
Definition: path.h:273
std::map< class TfToken, VtValue, TfDictionaryLessThan > UsdMetadataValueMap
Definition: common.h:64
const TfToken & GetName() const
Definition: object.h:221
USD_API VtDictionary GetAssetInfo() const
USD_API bool HasAuthoredAssetInfoKey(const TfToken &keyPath) const
SDF_API const TfToken & GetNameToken() const
UsdObject(const Usd_PrimDataHandle &prim, const SdfPath &proxyPrimPath)
Definition: object.h:681
USD_API bool ClearMetadataByDictKey(const TfToken &key, const TfToken &keyPath) const
USD_API bool HasAssetInfoKey(const TfToken &keyPath) const
USD_API UsdStageWeakPtr GetStage() const
T As() const
Definition: object.h:229
SDF_API SdfPath AppendProperty(TfToken const &propName) const
UsdObject(UsdObjType objType, const Usd_PrimDataHandle &prim, const SdfPath &proxyPrimPath, const TfToken &propName)
Definition: object.h:691
const Usd_PrimDataHandle & _Prim() const
Definition: object.h:711
UsdPrim GetPrim() const
Definition: prim.h:2787
GLfloat GLfloat GLfloat GLfloat h
Definition: glcorearb.h:2002
bool UsdIsConvertible(UsdObjType from, UsdObjType to)
Definition: object.h:77
SdfPath GetPath() const
Definition: object.h:186
USD_API std::string GetDescription() const
USD_API bool ClearDisplayName() const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
bool IsValid() const
Return true if this is a valid object, false otherwise.
Definition: object.h:126
SdfSpecType
Definition: types.h:68
friend UsdObjType Usd_GetObjType(const UsdObject &obj)
Definition: object.h:725
friend bool operator==(const UsdObject &lhs, const UsdObject &rhs)
Definition: object.h:147
friend bool operator!=(const UsdObject &lhs, const UsdObject &rhs)
Definition: object.h:156
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
USD_API UsdMetadataValueMap GetAllMetadata() const
bool Is() const
Definition: object.h:240
friend void TfHashAppend(HashState &h, const UsdObject &obj)
Definition: object.h:174
USD_API bool HasAssetInfo() const
USD_API bool HasAuthoredDisplayName() const
const TfToken & _PropName() const
Definition: object.h:714
USD_API std::string GetDocumentation() const
USD_API bool SetDocumentation(const std::string &doc) const
Sets this object's documentation (metadata). Returns true on success.
USD_API bool HasAuthoredCustomDataKey(const TfToken &keyPath) const
bool SetMetadataByDictKey(const TfToken &key, const TfToken &keyPath, const T &value) const
Definition: object.h:765
USD_API bool HasMetadataDictKey(const TfToken &key, const TfToken &keyPath) const
USD_API bool HasAuthoredCustomData() const
USD_API std::string GetDisplayName() const
Definition: value.h:146
USD_API bool ClearHidden() const
Clears the opinion for "Hidden" at the current EditTarget.
PXR_NAMESPACE_OPEN_SCOPE TF_DECLARE_WEAK_PTRS(UsdStage)
USD_API bool HasAuthoredDocumentation() const