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