stage.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_STAGE_H
25 #define PXR_USD_USD_STAGE_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/editTarget.h"
34 #include "pxr/usd/usd/schemaRegistry.h"
36 #include "pxr/usd/usd/stagePopulationMask.h"
37 #include "pxr/usd/usd/primFlags.h"
38 
40 #include "pxr/base/tf/hashmap.h"
41 #include "pxr/base/tf/weakBase.h"
42 
43 #include "pxr/usd/ar/ar.h"
44 #include "pxr/usd/ar/notice.h"
46 #include "pxr/usd/sdf/notice.h"
47 #include "pxr/usd/sdf/path.h"
48 #include "pxr/usd/sdf/types.h"
49 #include "pxr/usd/pcp/cache.h"
50 #include "pxr/base/vt/value.h"
52 
53 #include <boost/optional.hpp>
54 
55 #include <tbb/concurrent_vector.h>
56 #include <tbb/concurrent_unordered_set.h>
57 #include <tbb/concurrent_hash_map.h>
58 #include <tbb/spin_rw_mutex.h>
59 
60 #include <functional>
61 #include <string>
62 #include <memory>
63 #include <unordered_map>
64 #include <utility>
65 
66 PXR_NAMESPACE_OPEN_SCOPE
67 
68 
69 class ArResolverContext;
70 class GfInterval;
72 class Usd_ClipCache;
73 class Usd_InstanceCache;
74 class Usd_InstanceChanges;
75 class Usd_InterpolatorBase;
76 class UsdResolveInfo;
77 class UsdResolveTarget;
78 class Usd_Resolver;
79 class UsdPrim;
80 class UsdPrimRange;
81 
82 SDF_DECLARE_HANDLES(SdfLayer);
83 
147 class UsdStage : public TfRefBase, public TfWeakBase {
148 public:
149 
150  // --------------------------------------------------------------------- //
154  // --------------------------------------------------------------------- //
155 
161  {
164  };
165 
176  //
188  USD_API
189  static UsdStageRefPtr
190  CreateNew(const std::string& identifier,
191  InitialLoadSet load = LoadAll);
193  USD_API
194  static UsdStageRefPtr
195  CreateNew(const std::string& identifier,
196  const SdfLayerHandle& sessionLayer,
197  InitialLoadSet load = LoadAll);
199  USD_API
200  static UsdStageRefPtr
201  CreateNew(const std::string& identifier,
202  const SdfLayerHandle& sessionLayer,
203  const ArResolverContext& pathResolverContext,
204  InitialLoadSet load = LoadAll);
206  USD_API
207  static UsdStageRefPtr
208  CreateNew(const std::string& identifier,
209  const ArResolverContext& pathResolverContext,
210  InitialLoadSet load = LoadAll);
211 
229  USD_API
230  static UsdStageRefPtr
233  USD_API
234  static UsdStageRefPtr
235  CreateInMemory(const std::string& identifier,
236  InitialLoadSet load = LoadAll);
238  USD_API
239  static UsdStageRefPtr
240  CreateInMemory(const std::string& identifier,
241  const ArResolverContext& pathResolverContext,
242  InitialLoadSet load = LoadAll);
244  USD_API
245  static UsdStageRefPtr
246  CreateInMemory(const std::string& identifier,
247  const SdfLayerHandle &sessionLayer,
248  InitialLoadSet load = LoadAll);
250  USD_API
251  static UsdStageRefPtr
252  CreateInMemory(const std::string& identifier,
253  const SdfLayerHandle &sessionLayer,
254  const ArResolverContext& pathResolverContext,
255  InitialLoadSet load = LoadAll);
256 
272  USD_API
273  static UsdStageRefPtr
274  Open(const std::string& filePath, InitialLoadSet load = LoadAll);
276  USD_API
277  static UsdStageRefPtr
278  Open(const std::string& filePath,
279  const ArResolverContext& pathResolverContext,
280  InitialLoadSet load = LoadAll);
281 
299  USD_API
300  static UsdStageRefPtr
301  OpenMasked(const std::string &filePath,
302  UsdStagePopulationMask const &mask,
303  InitialLoadSet load = LoadAll);
305  USD_API
306  static UsdStageRefPtr
307  OpenMasked(const std::string &filePath,
308  const ArResolverContext &pathResolverContext,
309  UsdStagePopulationMask const &mask,
310  InitialLoadSet load = LoadAll);
311 
340  USD_API
341  static UsdStageRefPtr
342  Open(const SdfLayerHandle& rootLayer,
343  InitialLoadSet load=LoadAll);
345  USD_API
346  static UsdStageRefPtr
347  Open(const SdfLayerHandle& rootLayer,
348  const SdfLayerHandle& sessionLayer,
349  InitialLoadSet load=LoadAll);
351  USD_API
352  static UsdStageRefPtr
353  Open(const SdfLayerHandle& rootLayer,
354  const ArResolverContext& pathResolverContext,
355  InitialLoadSet load=LoadAll);
357  USD_API
358  static UsdStageRefPtr
359  Open(const SdfLayerHandle& rootLayer,
360  const SdfLayerHandle& sessionLayer,
361  const ArResolverContext& pathResolverContext,
362  InitialLoadSet load=LoadAll);
363 
384  USD_API
385  static UsdStageRefPtr
386  OpenMasked(const SdfLayerHandle& rootLayer,
387  const UsdStagePopulationMask &mask,
388  InitialLoadSet load=LoadAll);
390  USD_API
391  static UsdStageRefPtr
392  OpenMasked(const SdfLayerHandle& rootLayer,
393  const SdfLayerHandle& sessionLayer,
394  const UsdStagePopulationMask &mask,
395  InitialLoadSet load=LoadAll);
397  USD_API
398  static UsdStageRefPtr
399  OpenMasked(const SdfLayerHandle& rootLayer,
400  const ArResolverContext& pathResolverContext,
401  const UsdStagePopulationMask &mask,
402  InitialLoadSet load=LoadAll);
404  USD_API
405  static UsdStageRefPtr
406  OpenMasked(const SdfLayerHandle& rootLayer,
407  const SdfLayerHandle& sessionLayer,
408  const ArResolverContext& pathResolverContext,
409  const UsdStagePopulationMask &mask,
410  InitialLoadSet load=LoadAll);
411 
412  USD_API
413  virtual ~UsdStage();
414 
432  USD_API
433  void Reload();
434 
443  USD_API
444  static bool
445  IsSupportedFile(const std::string& filePath);
446 
448 
449  // --------------------------------------------------------------------- //
458 
466  USD_API
467  void Save();
468 
476  USD_API
477  void SaveSessionLayers();
478 
480 
481  // --------------------------------------------------------------------- //
527 
529  USD_API
531 
537  USD_API
538  static void
540 
542 
543  // --------------------------------------------------------------------- //
572  // --------------------------------------------------------------------- //
573 
581  USD_API
584 
590  USD_API
591  void Unload(const SdfPath& path=SdfPath::AbsoluteRootPath());
592 
604  USD_API
605  void LoadAndUnload(const SdfPathSet &loadSet, const SdfPathSet &unloadSet,
607 
618  USD_API
619  SdfPathSet GetLoadSet();
620 
640  USD_API
641  SdfPathSet FindLoadable(
642  const SdfPath& rootPath = SdfPath::AbsoluteRootPath());
643 
650  return _loadRules;
651  }
652 
662  USD_API
663  void SetLoadRules(UsdStageLoadRules const &rules);
664 
667  return _populationMask;
668  }
669 
671  USD_API
672  void SetPopulationMask(UsdStagePopulationMask const &mask);
673 
685  USD_API
687  std::function<bool (UsdRelationship const &)> const &relPred = nullptr,
688  std::function<bool (UsdAttribute const &)> const &attrPred = nullptr);
689 
691 
692  // --------------------------------------------------------------------- //
701  // --------------------------------------------------------------------- //
702 
712  USD_API
713  UsdPrim GetPseudoRoot() const;
714 
721  USD_API
722  UsdPrim GetDefaultPrim() const;
723 
731  USD_API
732  void SetDefaultPrim(const UsdPrim &prim);
733 
741  USD_API
742  void ClearDefaultPrim();
743 
751  USD_API
752  bool HasDefaultPrim() const;
753 
763  USD_API
764  UsdPrim GetPrimAtPath(const SdfPath &path) const;
765 
790  USD_API
791  UsdObject GetObjectAtPath(const SdfPath &path) const;
792 
801  USD_API
802  UsdProperty GetPropertyAtPath(const SdfPath &path) const;
803 
812  USD_API
813  UsdAttribute GetAttributeAtPath(const SdfPath &path) const;
814 
823  USD_API
824  UsdRelationship GetRelationshipAtPath(const SdfPath &path) const;
825 private:
826  // Return the primData object at \p path.
827  Usd_PrimDataConstPtr _GetPrimDataAtPath(const SdfPath &path) const;
828  Usd_PrimDataPtr _GetPrimDataAtPath(const SdfPath &path);
829 
830  // Return the primData object at \p path. If \p path indicates a prim
831  // beneath an instance, return the primData object for the corresponding
832  // prim in the instance's prototype.
833  Usd_PrimDataConstPtr
834  _GetPrimDataAtPathOrInPrototype(const SdfPath &path) const;
835 
837  std::vector<UsdPrim>
838  _GetInstancesForPrototype(const UsdPrim& prototype) const;
839 
840 public:
841 
858  USD_API
860 
865  USD_API
866  UsdPrimRange Traverse(const Usd_PrimFlagsPredicate &predicate);
867 
872  USD_API
874 
893  USD_API
894  UsdPrim OverridePrim(const SdfPath &path);
895 
919  USD_API
920  UsdPrim DefinePrim(const SdfPath &path,
921  const TfToken &typeName=TfToken());
922 
935  USD_API
936  UsdPrim CreateClassPrim(const SdfPath &rootPrimPath);
937 
959  USD_API
960  bool RemovePrim(const SdfPath& path);
961 
963 
964  // --------------------------------------------------------------------- //
968  // --------------------------------------------------------------------- //
969 
971  USD_API
972  SdfLayerHandle GetSessionLayer() const;
973 
975  USD_API
976  SdfLayerHandle GetRootLayer() const;
977 
982  USD_API
984 
994  USD_API
995  std::string
996  ResolveIdentifierToEditTarget(std::string const &identifier) const;
997 
1004  USD_API
1005  SdfLayerHandleVector GetLayerStack(bool includeSessionLayers=true) const;
1006 
1018  USD_API
1019  SdfLayerHandleVector GetUsedLayers(bool includeClipLayers=true) const;
1020 
1023  USD_API
1024  bool HasLocalLayer(const SdfLayerHandle &layer) const;
1025 
1027  USD_API
1028  const UsdEditTarget &GetEditTarget() const;
1029 
1033  USD_API
1035 
1039  USD_API
1040  UsdEditTarget GetEditTargetForLocalLayer(const SdfLayerHandle &layer);
1041 
1048  USD_API
1049  void SetEditTarget(const UsdEditTarget &editTarget);
1050 
1077  USD_API
1078  void MuteLayer(const std::string &layerIdentifier);
1079 
1082  USD_API
1083  void UnmuteLayer(const std::string &layerIdentifier);
1084 
1092  USD_API
1093  void MuteAndUnmuteLayers(const std::vector<std::string> &muteLayers,
1094  const std::vector<std::string> &unmuteLayers);
1095 
1097  USD_API
1098  const std::vector<std::string>& GetMutedLayers() const;
1099 
1104  USD_API
1105  bool IsLayerMuted(const std::string& layerIdentifier) const;
1106 
1108 
1109  // --------------------------------------------------------------------- //
1113  // --------------------------------------------------------------------- //
1114  // Future Work:
1115  // * Flatten sub-trees or individual prims
1116  // * Allow flattening of local LayerStack
1117  // * Move Flatten into a free-function to ensure it doesn't rely on
1118  // Stage internals.
1119 
1127  USD_API
1128  bool Export(const std::string &filename,
1129  bool addSourceFileComment=true,
1130  const SdfLayer::FileFormatArguments &args =
1132 
1140  USD_API
1141  bool ExportToString(std::string *result,
1142  bool addSourceFileComment=true) const;
1143 
1170  USD_API
1171  SdfLayerRefPtr Flatten(bool addSourceFileComment=true) const;
1173 
1174 public:
1175  // --------------------------------------------------------------------- //
1183  // --------------------------------------------------------------------- //
1184 
1196  template <class T>
1197  bool GetMetadata(const TfToken &key, T *value) const;
1199  USD_API
1200  bool GetMetadata(const TfToken &key, VtValue *value) const;
1201 
1208  USD_API
1209  bool HasMetadata(const TfToken &key) const;
1210 
1219  USD_API
1220  bool HasAuthoredMetadata(const TfToken &key) const;
1221 
1230  template<typename T>
1231  bool SetMetadata(const TfToken &key, const T &value) const;
1233  USD_API
1234  bool SetMetadata(const TfToken &key, const VtValue &value) const;
1235 
1244  USD_API
1245  bool ClearMetadata(const TfToken &key) const;
1246 
1262  template<typename T>
1263  bool GetMetadataByDictKey(const TfToken& key, const TfToken &keyPath,
1264  T* value) const;
1266  USD_API
1267  bool GetMetadataByDictKey(
1268  const TfToken& key, const TfToken &keyPath, VtValue *value) const;
1269 
1280  USD_API
1281  bool HasMetadataDictKey(
1282  const TfToken& key, const TfToken &keyPath) const;
1283 
1292  USD_API
1294  const TfToken& key, const TfToken &keyPath) const;
1295 
1307  template<typename T>
1308  bool SetMetadataByDictKey(const TfToken& key, const TfToken &keyPath,
1309  const T& value) const;
1311  USD_API
1312  bool SetMetadataByDictKey(
1313  const TfToken& key, const TfToken &keyPath, const VtValue& value) const;
1314 
1326  USD_API
1328  const TfToken& key, const TfToken& keyPath) const;
1329 
1348  USD_API
1349  void WriteFallbackPrimTypes();
1350 
1352 
1353  // --------------------------------------------------------------------- //
1360  // --------------------------------------------------------------------- //
1364  USD_API
1365  double GetStartTimeCode() const;
1366 
1373  USD_API
1374  void SetStartTimeCode(double);
1375 
1379  USD_API
1380  double GetEndTimeCode() const;
1381 
1388  USD_API
1389  void SetEndTimeCode(double);
1390 
1393  USD_API
1394  bool HasAuthoredTimeCodeRange() const;
1395 
1411  USD_API
1412  double GetTimeCodesPerSecond() const;
1413 
1422  USD_API
1423  void SetTimeCodesPerSecond(double timeCodesPerSecond) const;
1424 
1434  USD_API
1435  double GetFramesPerSecond() const;
1436 
1445  USD_API
1446  void SetFramesPerSecond(double framesPerSecond) const;
1447 
1449 
1450  // --------------------------------------------------------------------- //
1496  // --------------------------------------------------------------------- //
1497 
1503  USD_API
1504  void SetColorConfiguration(const SdfAssetPath &colorConfig) const;
1505 
1510  USD_API
1512 
1517  USD_API
1518  void SetColorManagementSystem(const TfToken &cms) const;
1519 
1524  USD_API
1526 
1538  USD_API
1539  static void GetColorConfigFallbacks(SdfAssetPath *colorConfiguration,
1540  TfToken *colorManagementSystem);
1541 
1555  USD_API
1556  static void
1557  SetColorConfigFallbacks(const SdfAssetPath &colorConfiguration,
1558  const TfToken &colorManagementSystem);
1559 
1561 
1562  // --------------------------------------------------------------------- //
1569  // --------------------------------------------------------------------- //
1570 
1575  USD_API
1576  void SetInterpolationType(UsdInterpolationType interpolationType);
1577 
1580  USD_API
1582 
1584 
1585  // --------------------------------------------------------------------- //
1590  // --------------------------------------------------------------------- //
1591 
1593  USD_API
1594  std::vector<UsdPrim> GetPrototypes() const;
1595 
1597 
1598 private:
1599  struct _IncludePayloadsPredicate;
1600 
1601  // --------------------------------------------------------------------- //
1602  // Stage Construction & Initialization
1603  // --------------------------------------------------------------------- //
1604 
1605  UsdStage(const SdfLayerRefPtr& rootLayer,
1606  const SdfLayerRefPtr& sessionLayer,
1607  const ArResolverContext& pathResolverContext,
1608  const UsdStagePopulationMask& mask,
1609  InitialLoadSet load);
1610 
1611  // Helper for Open() overloads -- searches and publishes to bound caches.
1612  template <class... Args>
1613  static UsdStageRefPtr _OpenImpl(InitialLoadSet load, Args const &... args);
1614 
1615  // Releases resources used by this stage.
1616  void _Close();
1617 
1618  // Common ref ptr initialization, called by public, static constructors.
1619  //
1620  // This method will either return a valid refptr (if the stage is correctly
1621  // initialized) or it will return a null ref pointer, deleting the
1622  // raw stage pointer in the process.
1623  static UsdStageRefPtr
1624  _InstantiateStage(const SdfLayerRefPtr &rootLayer,
1625  const SdfLayerRefPtr &sessionLayer,
1626  const ArResolverContext &pathResolverContext,
1627  const UsdStagePopulationMask &mask,
1628  InitialLoadSet load);
1629 
1630  // --------------------------------------------------------------------- //
1631  // Spec Existence & Definition Helpers
1632  // --------------------------------------------------------------------- //
1633 
1634  SdfPropertySpecHandleVector
1635  _GetPropertyStack(const UsdProperty &prop, UsdTimeCode time) const;
1636 
1637  std::vector<std::pair<SdfPropertySpecHandle, SdfLayerOffset>>
1638  _GetPropertyStackWithLayerOffsets(
1639  const UsdProperty &prop, UsdTimeCode time) const;
1640 
1641  static SdfPrimSpecHandleVector
1642  _GetPrimStack(const UsdPrim &prim);
1643 
1644  static std::vector<std::pair<SdfPrimSpecHandle, SdfLayerOffset>>
1645  _GetPrimStackWithLayerOffsets(const UsdPrim &prim);
1646 
1647  SdfPropertySpecHandle
1648  _GetSchemaPropertySpec(const UsdPrim &prim, const TfToken &propName) const;
1649 
1650  SdfPropertySpecHandle
1651  _GetSchemaPropertySpec(const UsdProperty &prop) const;
1652 
1653  template <class PropType>
1655  _GetSchemaPropertySpec(const UsdProperty &prop) const;
1656 
1657  SdfAttributeSpecHandle
1658  _GetSchemaAttributeSpec(const UsdAttribute &attr) const;
1659 
1660  SdfRelationshipSpecHandle
1661  _GetSchemaRelationshipSpec(const UsdRelationship &rel) const;
1662 
1663  SdfPrimSpecHandle
1664  _CreatePrimSpecForEditing(const UsdPrim& prim);
1665 
1666  template <class PropType>
1668  _CreatePropertySpecForEditing(const UsdProperty &prop);
1669 
1670  SdfPropertySpecHandle
1671  _CreatePropertySpecForEditing(const UsdProperty &prop);
1672 
1673  SdfAttributeSpecHandle
1674  _CreateAttributeSpecForEditing(const UsdAttribute &attr);
1675 
1676  SdfRelationshipSpecHandle
1677  _CreateRelationshipSpecForEditing(const UsdRelationship &rel);
1678 
1679  // Check if the given path is valid to use with the prim creation API,
1680  // like DefinePrim. If it is valid, returns (true, GetPrimAtPath(path)).
1681  // Otherwise, returns (false, UsdPrim()).
1682  std::pair<bool, UsdPrim>
1683  _IsValidPathForCreatingPrim(const SdfPath &path) const;
1684 
1685  // Validates that editing a specified prim is allowed. If editing is not
1686  // allowed, issues a coding error like "Cannot <operation> ..." and
1687  // returns false. Otherwise, returns true.
1688  bool _ValidateEditPrim(const UsdPrim &prim, const char* operation) const;
1689  bool _ValidateEditPrimAtPath(const SdfPath &primPath,
1690  const char* operation) const;
1691 
1692  UsdPrim _DefinePrim(const SdfPath &path, const TfToken &typeName);
1693 
1694  bool _RemoveProperty(const SdfPath& path);
1695 
1696  UsdProperty _FlattenProperty(const UsdProperty &srcProp,
1697  const UsdPrim &dstParent,
1698  const TfToken &dstName);
1699 
1700  // --------------------------------------------------------------------- //
1701  // Value & Metadata Authoring
1702  // --------------------------------------------------------------------- //
1703 
1704  // Trait that allows us to call the correct versions of _SetValue and
1705  // _SetMetadata for types whose values need to be mapped when written to
1706  // different edit targets.
1707  template <class T>
1708  struct _IsEditTargetMappable {
1709  static const bool value =
1710  std::is_same<T, SdfTimeCode>::value ||
1711  std::is_same<T, VtArray<SdfTimeCode>>::value ||
1712  std::is_same<T, SdfTimeSampleMap>::value ||
1713  std::is_same<T, VtDictionary>::value;
1714  };
1715 
1716  // Set value for types that don't need to be mapped for edit targets.
1717  template <class T>
1718  typename std::enable_if<!_IsEditTargetMappable<T>::value, bool>::type
1719  _SetValue(
1720  UsdTimeCode time, const UsdAttribute &attr, const T &newValue);
1721 
1722  // Set value for types that do need to be mapped for edit targets.
1723  template <class T>
1724  typename std::enable_if<_IsEditTargetMappable<T>::value, bool>::type
1725  _SetValue(
1726  UsdTimeCode time, const UsdAttribute &attr, const T &newValue);
1727 
1728  // Set value for dynamically typed VtValue. Will map the value across edit
1729  // targets if the held value type supports it.
1730  bool _SetValue(
1731  UsdTimeCode time, const UsdAttribute &attr, const VtValue &newValue);
1732 
1733  template <class T>
1734  bool _SetEditTargetMappedValue(
1735  UsdTimeCode time, const UsdAttribute &attr, const T &newValue);
1736 
1737  template <class T>
1738  bool _SetValueImpl(
1739  UsdTimeCode time, const UsdAttribute &attr, const T& value);
1740 
1741  bool _ClearValue(UsdTimeCode time, const UsdAttribute &attr);
1742 
1743  // Set metadata for types that don't need to be mapped across edit targets.
1744  template <class T>
1745  typename std::enable_if<!_IsEditTargetMappable<T>::value, bool>::type
1746  _SetMetadata(const UsdObject &object, const TfToken& key,
1747  const TfToken &keyPath, const T& value);
1748 
1749  // Set metadata for types that do need to be mapped for edit targets.
1750  template <class T>
1751  typename std::enable_if<_IsEditTargetMappable<T>::value, bool>::type
1752  _SetMetadata(const UsdObject &object, const TfToken& key,
1753  const TfToken &keyPath, const T& value);
1754 
1755  // Set metadata for dynamically typed VtValue. Will map the value across
1756  // edit targets if the held value type supports it.
1757  USD_API
1758  bool _SetMetadata(const UsdObject &object,
1759  const TfToken& key,
1760  const TfToken &keyPath,
1761  const VtValue& value);
1762 
1763  template <class T>
1764  bool _SetEditTargetMappedMetadata(
1765  const UsdObject &obj, const TfToken& fieldName,
1766  const TfToken &keyPath, const T &newValue);
1767 
1768  template <class T>
1769  bool _SetMetadataImpl(
1770  const UsdObject &obj, const TfToken& fieldName,
1771  const TfToken &keyPath, const T &value);
1772 
1773  bool _ClearMetadata(const UsdObject &obj, const TfToken& fieldName,
1774  const TfToken &keyPath=TfToken());
1775 
1776  // --------------------------------------------------------------------- //
1777  // Misc Internal Helpers
1778  // --------------------------------------------------------------------- //
1779 
1780  // Pcp helpers.
1781  PcpCache const *_GetPcpCache() const { return _cache.get(); }
1782  PcpCache *_GetPcpCache() { return _cache.get(); }
1783 
1784  // Returns the PrimIndex, using the read-only PcpCache API. We expect prims
1785  // to be composed during initial stage composition, so this method should
1786  // not be used in that context.
1787  const PcpPrimIndex* _GetPcpPrimIndex(const SdfPath& primPath) const;
1788 
1789  // Helper to report pcp errors.
1790  void _ReportPcpErrors(const PcpErrorVector &errors,
1791  const std::string &context) const;
1792  void _ReportErrors(const PcpErrorVector &errors,
1793  const std::vector<std::string>& otherErrors,
1794  const std::string &context) const;
1795 
1796  // --------------------------------------------------------------------- //
1797  // Scenegraph Composition & Change Processing
1798  // --------------------------------------------------------------------- //
1799 
1800  // Compose the prim indexes in the subtrees rooted at the paths in
1801  // \p primIndexPaths. If \p instanceChanges is given, returns
1802  // changes to prototypes and instances due to the discovery of new instances
1803  // during composition.
1804  void _ComposePrimIndexesInParallel(
1805  const std::vector<SdfPath>& primIndexPaths,
1806  const std::string& context,
1807  Usd_InstanceChanges* instanceChanges = nullptr);
1808 
1809  // Recompose the subtree rooted at \p prim: compose its type, flags, and
1810  // list of children, then invoke _ComposeSubtree on all its children.
1811  void _ComposeSubtree(
1812  Usd_PrimDataPtr prim, Usd_PrimDataConstPtr parent,
1813  UsdStagePopulationMask const *mask,
1814  const SdfPath &primIndexPath = SdfPath());
1815  void _ComposeSubtreeImpl(
1816  Usd_PrimDataPtr prim, Usd_PrimDataConstPtr parent,
1817  UsdStagePopulationMask const *mask,
1818  const SdfPath &primIndexPath = SdfPath());
1819  void _ComposeSubtreesInParallel(
1820  const std::vector<Usd_PrimDataPtr> &prims,
1821  const std::vector<SdfPath> *primIndexPaths = nullptr);
1822 
1823  // Compose subtree rooted at \p prim under \p parent. This function
1824  // ensures that the appropriate prim index is specified for \p prim if
1825  // \p parent is in a prototype.
1826  void _ComposeChildSubtree(Usd_PrimDataPtr prim,
1827  Usd_PrimDataConstPtr parent,
1828  UsdStagePopulationMask const *mask);
1829 
1830  // Compose \p prim's list of children and make any modifications necessary
1831  // to its _children member and the stage's _primMap, including possibly
1832  // instantiating new prims, or destroying existing subtrees of prims. The
1833  // any newly created prims *do not* have their prim index, type, flags, or
1834  // children composed.
1835  //
1836  // Compose only \p prim's direct children if recurse=false. Otherwise
1837  // recompose every descendent of \p prim. Callers that pass recurse=false
1838  // should invoke _ComposeSubtree on any newly created prims to ensure caches
1839  // are correctly populated.
1840  void _ComposeChildren(Usd_PrimDataPtr prim,
1841  UsdStagePopulationMask const *mask, bool recurse);
1842 
1843  // Instantiate a prim instance. There must not already be an instance
1844  // at \p primPath.
1845  Usd_PrimDataPtr _InstantiatePrim(const SdfPath &primPath);
1846 
1847  // Instantiate a prototype prim and sets its parent to pseudoroot.
1848  // There must not already be a prototype at \p primPath.
1849  Usd_PrimDataPtr _InstantiatePrototypePrim(const SdfPath &primPath);
1850 
1851  // For \p prim and all of its descendants, remove from _primMap and empty
1852  // their _children vectors.
1853  void _DestroyPrim(Usd_PrimDataPtr prim);
1854 
1855  // Destroy the prim subtrees rooted at each path in \p paths. \p paths may
1856  // not contain any path that is a descendent of another path in \p paths.
1857  void _DestroyPrimsInParallel(const std::vector<SdfPath>& paths);
1858 
1859  // Invoke _DestroyPrim() on all of \p prim's direct children.
1860  void _DestroyDescendents(Usd_PrimDataPtr prim);
1861 
1862  // Returns true if the object at the given path is a descendant of
1863  // an instance prim, i.e. a prim beneath an instance prim, or a property
1864  // of a prim beneath an instance prim.
1865  bool _IsObjectDescendantOfInstance(const SdfPath& path) const;
1866 
1867  // If the given prim is an instance, returns the corresponding
1868  // prototype prim. Otherwise, returns an invalid prim.
1869  Usd_PrimDataConstPtr _GetPrototypeForInstance(Usd_PrimDataConstPtr p) const;
1870 
1871  // Returns the path of the Usd prim using the prim index at the given path.
1872  SdfPath _GetPrimPathUsingPrimIndexAtPath(const SdfPath& primIndexPath) const;
1873 
1874  // Update stage contents in response to changes in scene description.
1875  void _HandleLayersDidChange(const SdfNotice::LayersDidChangeSentPerLayer &);
1876 
1877  // Update stage contents in response to changes to the asset resolver.
1878  void _HandleResolverDidChange(const ArNotice::ResolverChanged &);
1879 
1880  // Process stage change information stored in _pendingChanges.
1881  // _pendingChanges will be set to nullptr by the end of the function.
1882  void _ProcessPendingChanges();
1883 
1884  // Remove scene description for the prim at \p fullPath in the current edit
1885  // target.
1886  bool _RemovePrim(const SdfPath& fullPath);
1887 
1888  SdfPrimSpecHandle _GetPrimSpec(const SdfPath& fullPath);
1889 
1890  // Find and return the defining spec type for the property spec at the given
1891  // path, or SdfSpecTypeUnknown if none exists. The defining spec type is
1892  // either the builtin definition's spec type, if the indicated property is
1893  // builtin, otherwise it's the strongest authored spec's type if one exists,
1894  // otherwise it's SdfSpecTypeUnknown.
1895  SdfSpecType _GetDefiningSpecType(Usd_PrimDataConstPtr primData,
1896  const TfToken &propName) const;
1897 
1898  // Helper to apply Pcp changes and recompose the scenegraph accordingly,
1899  // given an optional initial set of paths to recompose.
1900  void _Recompose(const PcpChanges &changes);
1901  template <class T>
1902  void _Recompose(const PcpChanges &changes, T *pathsToRecompose);
1903  template <class T>
1904  void _RecomposePrims(T *pathsToRecompose);
1905 
1906  // Helper for _Recompose to find the subtrees that need to be
1907  // fully recomposed and to recompose the name children of the
1908  // parents of these subtrees. Note that [start, finish) must be a
1909  // sorted range of paths with no descendent paths.
1910  template <class Iter>
1911  void _ComputeSubtreesToRecompose(Iter start, Iter finish,
1912  std::vector<Usd_PrimDataPtr>* recompose);
1913 
1914  // return true if the path is valid for load/unload operations.
1915  // This method will emit errors when invalid paths are encountered.
1916  bool _IsValidForLoad(const SdfPath& path) const;
1917  bool _IsValidForUnload(const SdfPath& path) const;
1918 
1919  // Discover all payloads in a given subtree, adding the path of each
1920  // discovered prim index to the \p primIndexPaths set. If specified,
1921  // the corresponding UsdPrim path will be added to the \p usdPrimPaths
1922  // set. The root path will be considered for inclusion in the result set.
1923  //
1924  // Note that some payloads may not be discoverable in until an ancestral
1925  // payload has been included. UsdStage::LoadAndUnload takes this into
1926  // account.
1927  void _DiscoverPayloads(const SdfPath& rootPath,
1928  UsdLoadPolicy policy,
1929  SdfPathSet* primIndexPaths,
1930  bool unloadedOnly = false,
1931  SdfPathSet* usdPrimPaths = nullptr) const;
1932 
1933  // ===================================================================== //
1934  // VALUE RESOLUTION //
1935  // ===================================================================== //
1936  // --------------------------------------------------------------------- //
1937  // Specialized Value Resolution
1938  // --------------------------------------------------------------------- //
1939 
1940  // Helpers for resolving values for metadata fields requiring
1941  // special behaviors.
1942  static SdfSpecifier _GetSpecifier(Usd_PrimDataConstPtr primData);
1943  static TfToken _GetKind(Usd_PrimDataConstPtr primData);
1944  static bool _IsActive(Usd_PrimDataConstPtr primData);
1945 
1946  // Custom is true if it is true anywhere in the stack.
1947  bool _IsCustom(const UsdProperty &prop) const;
1948 
1949  // Variability is determined by the weakest opinion in the stack.
1950  SdfVariability _GetVariability(const UsdProperty &prop) const;
1951 
1952  // Helper functions for resolving asset paths during value resolution.
1953  void _MakeResolvedAssetPaths(UsdTimeCode time, const UsdAttribute &attr,
1954  SdfAssetPath *assetPaths,
1955  size_t numAssetPaths,
1956  bool anchorAssetPathsOnly = false) const;
1957 
1958  void _MakeResolvedAssetPathsValue(UsdTimeCode time, const UsdAttribute &attr,
1959  VtValue *value,
1960  bool anchorAssetPathsOnly = false) const;
1961 
1962  void _MakeResolvedTimeCodes(UsdTimeCode time, const UsdAttribute &attr,
1963  SdfTimeCode *timeCodes,
1964  size_t numTimeCodes) const;
1965 
1966  void _MakeResolvedAttributeValue(UsdTimeCode time, const UsdAttribute &attr,
1967  VtValue *value) const;
1968 
1969  // --------------------------------------------------------------------- //
1970  // Metadata Resolution
1971  // --------------------------------------------------------------------- //
1972 
1973 public:
1974  // Trait that allows us to call the correct version of _GetMetadata for
1975  // types that require type specific value resolution as opposed to just
1976  // strongest opinion. These types also use type specific resolution
1977  // in _GetValue.
1978  template <class T>
1979  struct _HasTypeSpecificResolution {
1980  static const bool value =
1981  std::is_same<T, SdfAssetPath>::value ||
1982  std::is_same<T, VtArray<SdfAssetPath>>::value ||
1983  std::is_same<T, SdfTimeCode>::value ||
1984  std::is_same<T, VtArray<SdfTimeCode>>::value ||
1985  std::is_same<T, SdfTimeSampleMap>::value ||
1986  std::is_same<T, VtDictionary>::value;
1987  };
1988 
1989 private:
1990  // Get metadata for types that do not have type specific value resolution.
1991  template <class T>
1992  typename std::enable_if<!_HasTypeSpecificResolution<T>::value, bool>::type
1993  _GetMetadata(const UsdObject &obj,
1994  const TfToken& fieldName,
1995  const TfToken &keyPath,
1996  bool useFallbacks,
1997  T* result) const;
1998 
1999  // Get metadata for types that do have type specific value resolution.
2000  template <class T>
2001  typename std::enable_if<_HasTypeSpecificResolution<T>::value, bool>::type
2002  _GetMetadata(const UsdObject &obj,
2003  const TfToken& fieldName,
2004  const TfToken &keyPath,
2005  bool useFallbacks,
2006  T* result) const;
2007 
2008  // Get metadata as a dynamically typed VtValue. Will perform type specific
2009  // value resolution if the returned held type requires it.
2010  bool _GetMetadata(const UsdObject &obj,
2011  const TfToken& fieldName,
2012  const TfToken &keyPath,
2013  bool useFallbacks,
2014  VtValue* result) const;
2015 
2016  // Gets a metadata value using only strongest value resolution. It is
2017  // assumed that result is holding a value that does not require type
2018  // specific value resolution.
2019  USD_API
2020  bool _GetStrongestResolvedMetadata(const UsdObject &obj,
2021  const TfToken& fieldName,
2022  const TfToken &keyPath,
2023  bool useFallbacks,
2024  SdfAbstractDataValue* result) const;
2025 
2026  // Gets a metadata value with the type specific value resolution for the
2027  // type applied. This is only implemented for types that
2028  // _HasTypeSpecificResolution.
2029  template <class T>
2030  USD_API
2031  bool _GetTypeSpecificResolvedMetadata(const UsdObject &obj,
2032  const TfToken& fieldName,
2033  const TfToken &keyPath,
2034  bool useFallbacks,
2035  T* result) const;
2036 
2037  template <class Composer>
2038  void _GetAttrTypeImpl(const UsdAttribute &attr,
2039  const TfToken &fieldName,
2040  bool useFallbacks,
2041  Composer *composer) const;
2042 
2043  template <class Composer>
2044  void _GetAttrVariabilityImpl(const UsdAttribute &attr,
2045  bool useFallbacks,
2046  Composer *composer) const;
2047 
2048  template <class Composer>
2049  void _GetPropCustomImpl(const UsdProperty &prop,
2050  bool useFallbacks,
2051  Composer *composer) const;
2052 
2053  template <class Composer>
2054  bool _GetSpecialPropMetadataImpl(const UsdObject &obj,
2055  const TfToken &fieldName,
2056  const TfToken &keyPath,
2057  bool useFallbacks,
2058  Composer *composer) const;
2059  template <class Composer>
2060  bool _GetMetadataImpl(const UsdObject &obj,
2061  const TfToken& fieldName,
2062  const TfToken& keyPath,
2063  bool includeFallbacks,
2064  Composer *composer) const;
2065 
2066  template <class Composer>
2067  bool _GetGeneralMetadataImpl(const UsdObject &obj,
2068  const TfToken& fieldName,
2069  const TfToken& keyPath,
2070  bool includeFallbacks,
2071  Composer *composer) const;
2072 
2073  // NOTE: The "authoredOnly" flag is not yet in use, but when we have
2074  // support for prim-based metadata fallbacks, they should be ignored when
2075  // this flag is set to true.
2076  bool _HasMetadata(const UsdObject &obj, const TfToken& fieldName,
2077  const TfToken &keyPath, bool useFallbacks) const;
2078 
2080  _ListMetadataFields(const UsdObject &obj, bool useFallbacks) const;
2081 
2082  void _GetAllMetadata(const UsdObject &obj,
2083  bool useFallbacks,
2084  UsdMetadataValueMap* result,
2085  bool anchorAssetPathsOnly = false) const;
2086 
2087  // --------------------------------------------------------------------- //
2088  // Default & TimeSample Resolution
2089  // --------------------------------------------------------------------- //
2090 
2091  void _GetResolveInfo(const UsdAttribute &attr,
2092  UsdResolveInfo *resolveInfo,
2093  const UsdTimeCode *time = nullptr) const;
2094 
2095  void _GetResolveInfoWithResolveTarget(
2096  const UsdAttribute &attr,
2097  const UsdResolveTarget &resolveTarget,
2098  UsdResolveInfo *resolveInfo,
2099  const UsdTimeCode *time = nullptr) const;
2100 
2101  template <class T> struct _ExtraResolveInfo;
2102 
2103  // Gets the value resolve info for the given attribute. If time is provided,
2104  // the resolve info is evaluated for that specific time (which may be
2105  // default). Otherwise, if time is null, the resolve info is evaluated for
2106  // "any numeric time" and will not populate values in extraInfo that
2107  // require a specific time to be evaluated.
2108  template <class T>
2109  void _GetResolveInfo(const UsdAttribute &attr,
2110  UsdResolveInfo *resolveInfo,
2111  const UsdTimeCode *time = nullptr,
2112  _ExtraResolveInfo<T> *extraInfo = nullptr) const;
2113 
2114  // Gets the value resolve info for the given attribute using the given
2115  // resolve target. If time is provided, the resolve info is evaluated for
2116  // that specific time (which may be default). Otherwise, if time is null,
2117  // the resolve info is evaluated for "any numeric time" and will not
2118  // populate values in extraInfo that require a specific time to be
2119  // evaluated.
2120  template <class T>
2121  void _GetResolveInfoWithResolveTarget(
2122  const UsdAttribute &attr,
2123  const UsdResolveTarget &resolveTarget,
2124  UsdResolveInfo *resolveInfo,
2125  const UsdTimeCode *time = nullptr,
2126  _ExtraResolveInfo<T> *extraInfo = nullptr) const;
2127 
2128  // Shared implementation function for _GetResolveInfo and
2129  // _GetResolveInfoWithResolveTarget. The only difference between how these
2130  // two functions behave is in how they create the Usd_Resolver used for
2131  // iterating over nodes and layers, thus they provide this implementation
2132  // with the needed MakeUsdResolverFn to create the Usd_Resolver.
2133  template <class T, class MakeUsdResolverFn>
2134  void _GetResolveInfoImpl(const UsdAttribute &attr,
2135  UsdResolveInfo *resolveInfo,
2136  const UsdTimeCode *time,
2137  _ExtraResolveInfo<T> *extraInfo,
2138  const MakeUsdResolverFn &makeUsdResolveFn) const;
2139 
2140  template <class T> struct _ResolveInfoResolver;
2141  struct _PropertyStackResolver;
2142 
2143  template <class Resolver, class MakeUsdResolverFn>
2144  void _GetResolvedValueAtDefaultImpl(
2145  const UsdProperty &prop,
2146  Resolver *resolver,
2147  const MakeUsdResolverFn &makeUsdResolverFn) const;
2148 
2149  template <class Resolver, class MakeUsdResolverFn>
2150  void _GetResolvedValueAtTimeImpl(
2151  const UsdProperty &prop,
2152  Resolver *resolver,
2153  const double *time,
2154  const MakeUsdResolverFn &makeUsdResolverFn) const;
2155 
2156  bool _GetValue(UsdTimeCode time, const UsdAttribute &attr,
2157  VtValue* result) const;
2158 
2159  template <class T>
2160  bool _GetValue(UsdTimeCode time, const UsdAttribute &attr,
2161  T* result) const;
2162 
2163  template <class T>
2164  bool _GetValueImpl(UsdTimeCode time, const UsdAttribute &attr,
2165  Usd_InterpolatorBase* interpolator,
2166  T* value) const;
2167 
2169  _GetLayerWithStrongestValue(
2170  UsdTimeCode time, const UsdAttribute &attr) const;
2171 
2172 
2173 
2174  USD_API
2175  bool _GetValueFromResolveInfo(const UsdResolveInfo &info,
2176  UsdTimeCode time, const UsdAttribute &attr,
2177  VtValue* result) const;
2178 
2179  template <class T>
2180  USD_API
2181  bool _GetValueFromResolveInfo(const UsdResolveInfo &info,
2182  UsdTimeCode time, const UsdAttribute &attr,
2183  T* result) const;
2184 
2185  template <class T>
2186  bool _GetValueFromResolveInfoImpl(const UsdResolveInfo &info,
2187  UsdTimeCode time, const UsdAttribute &attr,
2188  Usd_InterpolatorBase* interpolator,
2189  T* value) const;
2190 
2191  template <class T>
2192  bool _GetDefaultValueFromResolveInfoImpl(const UsdResolveInfo &info,
2193  const UsdAttribute &attr,
2194  T* value) const;
2195 
2196  // --------------------------------------------------------------------- //
2197  // Specialized Time Sample I/O
2198  // --------------------------------------------------------------------- //
2199 
2206  bool _GetTimeSamplesInInterval(const UsdAttribute &attr,
2207  const GfInterval& interval,
2208  std::vector<double>* times) const;
2209 
2210  bool _GetTimeSamplesInIntervalFromResolveInfo(
2211  const UsdResolveInfo &info,
2212  const UsdAttribute &attr,
2213  const GfInterval& interval,
2214  std::vector<double>* times) const;
2215 
2216  size_t _GetNumTimeSamples(const UsdAttribute &attr) const;
2217 
2218  size_t _GetNumTimeSamplesFromResolveInfo(const UsdResolveInfo &info,
2219  const UsdAttribute &attr) const;
2220 
2224  bool _GetBracketingTimeSamples(const UsdAttribute &attr,
2225  double desiredTime,
2226  bool authoredOnly,
2227  double* lower,
2228  double* upper,
2229  bool* hasSamples) const;
2230 
2231  bool _GetBracketingTimeSamplesFromResolveInfo(const UsdResolveInfo &info,
2232  const UsdAttribute &attr,
2233  double desiredTime,
2234  bool authoredOnly,
2235  double* lower,
2236  double* upper,
2237  bool* hasSamples) const;
2238 
2239  bool _ValueMightBeTimeVarying(const UsdAttribute &attr) const;
2240 
2241  bool _ValueMightBeTimeVaryingFromResolveInfo(const UsdResolveInfo &info,
2242  const UsdAttribute &attr) const;
2243 
2244  void _RegisterPerLayerNotices();
2245  void _RegisterResolverChangeNotice();
2246 
2247 private:
2248 
2249  // The 'pseudo root' prim.
2250  Usd_PrimDataPtr _pseudoRoot;
2251 
2252  // The stage's root layer.
2253  SdfLayerRefPtr _rootLayer;
2254 
2255  // Every UsdStage has an implicit, in-memory session layer.
2256  // This is to allow for runtime overrides such as variant selections.
2257  SdfLayerRefPtr _sessionLayer;
2258 
2259  // The stage's EditTarget.
2260  UsdEditTarget _editTarget;
2261  bool _editTargetIsLocalLayer;
2262 
2263  std::unique_ptr<PcpCache> _cache;
2264  std::unique_ptr<Usd_ClipCache> _clipCache;
2265  std::unique_ptr<Usd_InstanceCache> _instanceCache;
2266 
2267  TfHashMap<TfToken, TfToken, TfHash> _invalidPrimTypeToFallbackMap;
2268 
2269  size_t _usedLayersRevision;
2270 
2271  // A concurrent map from Path to Prim, for fast random access.
2272  struct _TbbHashEq {
2273  inline bool equal(SdfPath const &l, SdfPath const &r) const {
2274  return l == r;
2275  }
2276  inline size_t hash(SdfPath const &path) const {
2277  return path.GetHash();
2278  }
2279  };
2280  using PathToNodeMap = tbb::concurrent_hash_map<
2281  SdfPath, Usd_PrimDataIPtr, _TbbHashEq>;
2282  PathToNodeMap _primMap;
2283 
2284  // The interpolation type used for all attributes on the stage.
2285  UsdInterpolationType _interpolationType;
2286 
2287  typedef std::vector<
2288  std::pair<SdfLayerHandle, TfNotice::Key> > _LayerAndNoticeKeyVec;
2289  _LayerAndNoticeKeyVec _layersAndNoticeKeys;
2290  size_t _lastChangeSerialNumber;
2291 
2292  TfNotice::Key _resolverChangeKey;
2293 
2294  // Data for pending change processing.
2295  class _PendingChanges;
2296  _PendingChanges* _pendingChanges;
2297 
2298  boost::optional<WorkDispatcher> _dispatcher;
2299 
2300  // To provide useful aggregation of malloc stats, we bill everything
2301  // for this stage - from all access points - to this tag.
2302  char const *_mallocTagID;
2303 
2304  // The state used when instantiating the stage.
2305  const InitialLoadSet _initialLoadSet;
2306 
2307  // The population mask that applies to this stage.
2308  UsdStagePopulationMask _populationMask;
2309 
2310  // The load rules that apply to this stage.
2311  UsdStageLoadRules _loadRules;
2312 
2313  bool _isClosingStage;
2314  bool _isWritingFallbackPrimTypes;
2315 
2316  friend class UsdAPISchemaBase;
2317  friend class UsdAttribute;
2318  friend class UsdAttributeQuery;
2319  friend class UsdEditTarget;
2320  friend class UsdInherits;
2321  friend class UsdObject;
2322  friend class UsdPrim;
2323  friend class UsdProperty;
2324  friend class UsdRelationship;
2325  friend class UsdSpecializes;
2326  friend class UsdVariantSet;
2327  friend class UsdVariantSets;
2328  friend class Usd_FlattenAccess;
2329  friend class Usd_PcpCacheAccess;
2330  friend class Usd_PrimData;
2331  friend class Usd_StageOpenRequest;
2332  template <class T> friend struct Usd_AttrGetValueHelper;
2333  friend struct Usd_AttrGetUntypedValueHelper;
2334  template <class RefsOrPayloadsEditorType, class RefsOrPayloadsProxyType>
2335  friend struct Usd_ListEditImpl;
2336 };
2337 
2338 // UsdObject's typed metadata query relies on this specialization being
2339 // externally visible and exporting the primary template does not
2340 // automatically export this specialization.
2341 template <>
2342 USD_API
2343 bool
2344 UsdStage::_GetTypeSpecificResolvedMetadata(const UsdObject &obj,
2345  const TfToken& fieldName,
2346  const TfToken &keyPath,
2347  bool useFallbacks,
2348  SdfTimeSampleMap* result) const;
2349 
2350 template<typename T>
2351 bool
2352 UsdStage::GetMetadata(const TfToken& key, T* value) const
2353 {
2354  VtValue result;
2355  if (!GetMetadata(key, &result)){
2356  return false;
2357  }
2358 
2359  if (result.IsHolding<T>()){
2360  *value = result.UncheckedGet<T>();
2361  return true;
2362  } else {
2363  TF_CODING_ERROR("Requested type %s for stage metadatum %s does not"
2364  " match retrieved type %s",
2365  ArchGetDemangled<T>().c_str(),
2366  key.GetText(),
2367  result.GetTypeName().c_str());
2368  return false;
2369  }
2370 }
2371 
2372 template<typename T>
2373 bool
2374 UsdStage::SetMetadata(const TfToken& key, const T& value) const
2375 {
2376  VtValue in(value);
2377  return SetMetadata(key, in);
2378 }
2379 
2380 template<typename T>
2381 bool
2382 UsdStage::GetMetadataByDictKey(const TfToken& key, const TfToken &keyPath,
2383  T* value) const
2384 {
2385  VtValue result;
2386  if (!GetMetadataByDictKey(key, keyPath, &result)){
2387  return false;
2388  }
2389 
2390  if (result.IsHolding<T>()){
2391  *value = result.UncheckedGet<T>();
2392  return true;
2393  } else {
2394  TF_CODING_ERROR("Requested type %s for stage metadatum %s[%s] does not"
2395  " match retrieved type %s",
2396  ArchGetDemangled<T>().c_str(),
2397  key.GetText(),
2398  keyPath.GetText(),
2399  result.GetTypeName().c_str());
2400  return false;
2401  }
2402 }
2403 
2404 template<typename T>
2405 bool
2406 UsdStage::SetMetadataByDictKey(const TfToken& key, const TfToken &keyPath,
2407  const T& value) const
2408 {
2409  VtValue in(value);
2410  return SetMetadataByDictKey(key, keyPath, in);
2411 }
2412 
2413 // Get metadata for types that do not have type specific value resolution.
2414 template <class T>
2415 typename std::enable_if<
2416  !UsdStage::_HasTypeSpecificResolution<T>::value, bool>::type
2417 UsdStage::_GetMetadata(const UsdObject &obj,
2418  const TfToken& fieldName,
2419  const TfToken &keyPath,
2420  bool useFallbacks,
2421  T* result) const
2422 {
2423  // Since these types don't have type specific value resolution, we can just
2424  // get the strongest metadata value and be done.
2425  SdfAbstractDataTypedValue<T> out(result);
2426  return _GetStrongestResolvedMetadata(
2427  obj, fieldName, keyPath, useFallbacks, &out);
2428 }
2429 
2430 // Get metadata for types that do have type specific value resolution.
2431 template <class T>
2432 typename std::enable_if<
2433  UsdStage::_HasTypeSpecificResolution<T>::value, bool>::type
2434 UsdStage::_GetMetadata(const UsdObject &obj,
2435  const TfToken& fieldName,
2436  const TfToken &keyPath,
2437  bool useFallbacks,
2438  T* result) const
2439 {
2440  // Call the templated type specifice resolved metadata implementation that
2441  // will only be implemented for types that support it.
2442  return _GetTypeSpecificResolvedMetadata(
2443  obj, fieldName, keyPath, useFallbacks, result);
2444 }
2445 
2446 
2447 // Set metadata for types that don't need to be mapped across edit targets.
2448 template <class T>
2449 typename std::enable_if<!UsdStage::_IsEditTargetMappable<T>::value, bool>::type
2450 UsdStage::_SetMetadata(const UsdObject &object, const TfToken& key,
2451  const TfToken &keyPath, const T& value)
2452 {
2453  // Since we know that we don't need to map the value for edit targets,
2454  // we can just type erase the value and set the metadata as is.
2456  return _SetMetadataImpl<SdfAbstractDataConstValue>(
2457  object, key, keyPath, in);
2458 }
2459 
2460 // Set metadata for types that do need to be mapped for edit targets.
2461 template <class T>
2462 typename std::enable_if<UsdStage::_IsEditTargetMappable<T>::value, bool>::type
2463 UsdStage::_SetMetadata(const UsdObject &object, const TfToken& key,
2464  const TfToken &keyPath, const T& value)
2465 {
2466  return _SetEditTargetMappedMetadata(object, key, keyPath, value);
2467 }
2468 
2469 
2470 PXR_NAMESPACE_CLOSE_SCOPE
2471 
2472 #endif //PXR_USD_USD_STAGE_H
2473 
USD_API void ExpandPopulationMask(std::function< bool(UsdRelationship const &)> const &relPred=nullptr, std::function< bool(UsdAttribute const &)> const &attrPred=nullptr)
Expand this stage's population mask to include the targets of all relationships that pass relPred and...
static USD_API void SetGlobalVariantFallbacks(const PcpVariantFallbackMap &fallbacks)
Set the global variant fallback preferences used in new UsdStages.
A proxy class for applying listOp edits to the specializes list for a prim.
Definition: specializes.h:51
Handle-object returned by TfNotice::Register().
Definition: notice.h:256
A scene description container that can combine with other such containers to form simple component as...
Definition: layer.h:94
Load no loadable prims.
Definition: stage.h:163
USD_API void SetStartTimeCode(double)
Sets the stage's start timeCode.
USD_API UsdPrimRange Traverse()
Traverse the active, loaded, defined, non-abstract prims on this stage depth-first.
USD_API UsdPrim GetPrimAtPath(const SdfPath &path) const
Return the UsdPrim at path, or an invalid UsdPrim if none exists.
USD_API ArResolverContext GetPathResolverContext() const
Return the path resolver context for all path resolution during composition of this stage.
static USD_API void GetColorConfigFallbacks(SdfAssetPath *colorConfiguration, TfToken *colorManagementSystem)
Returns the global fallback values of 'colorConfiguration' and 'colorManagementSystem'.
static USD_API UsdStageRefPtr OpenMasked(const std::string &filePath, UsdStagePopulationMask const &mask, InitialLoadSet load=LoadAll)
Create a new stage and recursively compose prims defined within and referenced by the layer at filePa...
USD_API SdfLayerRefPtr Flatten(bool addSourceFileComment=true) const
Returns a single, anonymous, merged layer for this composite scene.
USD_API UsdPrim GetDefaultPrim() const
Return the root UsdPrim on this stage whose name is the root layer's defaultPrim metadata's value.
PcpPrimIndex is an index of the all sites of scene description that contribute opinions to a specific...
Definition: primIndex.h:76
USD_API void SetLoadRules(UsdStageLoadRules const &rules)
Set the UsdStageLoadRules to govern payload inclusion on this stage.
Standard pointer typedefs.
USD_API void SetDefaultPrim(const UsdPrim &prim)
Set the default prim layer metadata in this stage's root layer.
T const & UncheckedGet() const &
Returns a const reference to the held object if the held object is of type T.
Definition: value.h:1093
USD_API void SetInterpolationType(UsdInterpolationType interpolationType)
Sets the interpolation type used during value resolution for all attributes on this stage.
Describes Pcp changes.
Definition: changes.h:173
bool SetMetadata(const TfToken &key, const T &value) const
Set the value of Stage metadatum key to value, if the stage's current UsdEditTarget is the root or se...
Definition: stage.h:2374
The fully-typed container for a field value in an SdfAbstractData.
Definition: abstractData.h:561
USD_API UsdObject GetObjectAtPath(const SdfPath &path) const
Return the UsdObject at path, or an invalid UsdObject if none exists.
USD_API UsdPrim OverridePrim(const SdfPath &path)
Attempt to ensure a UsdPrim at path exists on this stage.
A type-erased container for a field value in an SdfAbstractData.
Definition: abstractData.h:415
Object for efficiently making repeated queries for attribute values.
USD_API bool Export(const std::string &filename, bool addSourceFileComment=true, const SdfLayer::FileFormatArguments &args=SdfLayer::FileFormatArguments()) const
Writes out the composite scene as a single flattened layer into filename.
USD_API void LoadAndUnload(const SdfPathSet &loadSet, const SdfPathSet &unloadSet, UsdLoadPolicy policy=UsdLoadWithDescendants)
Unload and load the given path sets.
USD_API SdfLayerHandleVector GetLayerStack(bool includeSessionLayers=true) const
Return this stage's local layers in strong-to-weak order.
bool GetMetadata(const TfToken &key, T *value) const
Return in value an authored or fallback value (if one was defined for the given metadatum) for Stage ...
Definition: stage.h:2352
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: stage.h:2406
USD_API UsdPrim CreateClassPrim(const SdfPath &rootPrimPath)
Author an SdfPrimSpec with specifier == SdfSpecifierClass for the class at root prim path path at the...
#define TF_CODING_ERROR(fmt, args)
Issue an internal programming error, but continue execution.
Definition: diagnostic.h:85
static USD_API UsdStageRefPtr CreateInMemory(InitialLoadSet load=LoadAll)
Creates a new stage only in memory, analogous to creating an anonymous SdfLayer.
USD_API std::vector< UsdPrim > GetPrototypes() const
Returns all native instancing prototype prims.
PcpCache is the context required to make requests of the Pcp composition algorithm and cache the resu...
Definition: cache.h:93
USD_API void SetTimeCodesPerSecond(double timeCodesPerSecond) const
Sets the stage's timeCodesPerSecond value.
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,...
static USD_API bool IsSupportedFile(const std::string &filePath)
Indicates whether the specified file is supported by UsdStage.
The outermost container for scene description, which owns and presents composed prims as a scenegraph...
Definition: stage.h:147
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.
VT_API std::string GetTypeName() const
Return the type name of the held typeid.
Load a prim plus all its descendants.
Definition: common.h:118
A proxy class for applying listOp edits to the inherit paths list for a prim.
Definition: inherits.h:51
USD_API void Save()
Calls SdfLayer::Save on all dirty layers contributing to this stage except session layers and sublaye...
USD_API std::string ResolveIdentifierToEditTarget(std::string const &identifier) const
Resolve the given identifier using this stage's ArResolverContext and the layer of its GetEditTarget(...
The base class for all API schemas.
Container for information about the source of an attribute's value, i.e.
Definition: resolveInfo.h:68
Scenegraph object for authoring and retrieving numeric, string, and array valued data,...
Definition: attribute.h:176
USD_API SdfAssetPath GetColorConfiguration() const
Returns the default color configuration used to interpret the per- attribute color-spaces in the comp...
SdfHandle is a smart ptr that calls IsDormant() on the pointed-to object as an extra expiration check...
UsdStagePopulationMask GetPopulationMask() const
Return this stage's population mask.
Definition: stage.h:666
Basic Sdf data types.
Enable a concrete base class for use with TfRefPtr.
Definition: refBase.h:71
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:87
USD_API bool IsLayerMuted(const std::string &layerIdentifier) const
Returns true if the layer specified by layerIdentifier is muted in this cache, false otherwise.
USD_API bool ClearMetadata(const TfToken &key) const
Clear the value of stage metadatum key, if the stage's current UsdEditTarget is the root or session l...
USD_API void UnmuteLayer(const std::string &layerIdentifier)
Unmute the layer identified by layerIdentifier if it had previously been muted.
USD_API double GetTimeCodesPerSecond() const
Returns the stage's timeCodesPerSecond value.
Value type that represents a time code.
Definition: timeCode.h:44
USD_API const std::vector< std::string > & GetMutedLayers() const
Returns a vector of all layers that have been muted on this stage.
A UsdVariantSet represents a single VariantSet in USD (e.g.
Definition: variantSets.h:56
USD_API bool HasAuthoredTimeCodeRange() const
Returns true if the stage has both start and end timeCodes authored in the session layer or the root ...
Represent a time value, which may be either numeric, holding a double value, or a sentinel value UsdT...
Definition: timeCode.h:85
USD_API const UsdEditTarget & GetEditTarget() const
Return the stage's EditTarget.
USD_API bool RemovePrim(const SdfPath &path)
Remove all scene description for the given path and its subtree in the current UsdEditTarget.
USD_API UsdProperty GetPropertyAtPath(const SdfPath &path) const
Return the UsdProperty at path, or an invalid UsdProperty if none exists.
USD_API double GetStartTimeCode() const
Returns the stage's start timeCode.
Base class for Usd scenegraph objects, providing common API.
Definition: object.h:130
Defines a mapping from scene graph paths to Sdf spec paths in a SdfLayer where edits should be direct...
Definition: editTarget.h:78
The fully-typed container for a field value in an SdfAbstractData.
Definition: abstractData.h:466
USD_API void MuteAndUnmuteLayers(const std::vector< std::string > &muteLayers, const std::vector< std::string > &unmuteLayers)
Mute and unmute the layers identified in muteLayers and unmuteLayers.
This class represents rules that govern payload inclusion on UsdStages.
USD_API UsdPrim GetPseudoRoot() const
Return the stage's "pseudo-root" prim, whose name is defined by Usd.
UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a "Prim" as ...
Definition: prim.h:134
InitialLoadSet
Specifies the initial set of prims to load when opening a UsdStage.
Definition: stage.h:160
SdfSpecifier
An enum that identifies the possible specifiers for an SdfPrimSpec.
Definition: types.h:122
std::map< std::string, std::string > FileFormatArguments
Type for specifying additional file format-specific arguments to layer API.
Definition: layer.h:120
USD_API double GetFramesPerSecond() const
Returns the stage's framesPerSecond value.
USD_API SdfPathSet GetLoadSet()
Returns a set of all loaded paths.
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:442
Notice sent when asset paths may resolve to a different path than before due to a change in the resol...
Definition: notice.h:65
A basic mathematical interval class.
Definition: interval.h:50
USD_API double GetEndTimeCode() const
Returns the stage's end timeCode.
USD_API SdfLayerHandle GetSessionLayer() const
Return this stage's root session layer.
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:290
USD_API UsdPrim DefinePrim(const SdfPath &path, const TfToken &typeName=TfToken())
Attempt to ensure a UsdPrim at path is defined (according to UsdPrim::IsDefined()) on this stage.
USD_API bool HasDefaultPrim() const
Return true if this stage's root layer has an authored opinion for the default prim layer metadata.
A UsdRelationship creates dependencies between scenegraph objects by allowing a prim to target other ...
Definition: relationship.h:128
USD_API UsdPrimRange TraverseAll()
Traverse all the prims on this stage depth-first.
USD_API void SaveSessionLayers()
Calls SdfLayer::Save on all dirty session layers and sublayers of session layers contributing to this...
USD_API void SetPopulationMask(UsdStagePopulationMask const &mask)
Set this stage's population mask and recompose the stage.
SdfVariability
An enum that identifies variability types for attributes.
Definition: types.h:178
bool GetMetadataByDictKey(const TfToken &key, const TfToken &keyPath, T *value) const
Resolve the requested dictionary sub-element keyPath of dictionary-valued metadatum named key,...
Definition: stage.h:2382
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.
static USD_API UsdStageRefPtr CreateNew(const std::string &identifier, InitialLoadSet load=LoadAll)
Create a new stage with root layer identifier, destroying potentially existing files with that identi...
USD_API bool HasLocalLayer(const SdfLayerHandle &layer) const
Return true if layer is one of the layers in this stage's local, root layerStack.
USD_API void SetEndTimeCode(double)
Sets the stage's end timeCode.
UsdLoadPolicy
Controls UsdStage::Load() and UsdPrim::Load() behavior regarding whether or not descendant prims are ...
Definition: common.h:116
Contains an asset path and an optional resolved path.
Definition: assetPath.h:47
USD_API UsdPrim Load(const SdfPath &path=SdfPath::AbsoluteRootPath(), UsdLoadPolicy policy=UsdLoadWithDescendants)
Modify this stage's load rules to load the prim at path, its ancestors, and all of its descendants if...
USD_API SdfLayerHandleVector GetUsedLayers(bool includeClipLayers=true) const
Return a vector of all of the layers currently consumed by this stage, as determined by the compositi...
Notice sent per-layer indicating all layers whose contents have changed within a single round of chan...
Definition: notice.h:110
Base class for UsdAttribute and UsdRelationship scenegraph objects.
Definition: property.h:55
An forward-iterable range that traverses a subtree of prims rooted at a given prim in depth-first ord...
Definition: primRange.h:118
USD_API UsdRelationship GetRelationshipAtPath(const SdfPath &path) const
Return the UsdAttribute at path, or an invalid UsdAttribute if none exists.
SdfSpecType
An enum that specifies the type of an object.
Definition: types.h:90
static SDF_API const SdfPath & AbsoluteRootPath()
The absolute path representing the top of the namespace hierarchy.
USD_API TfToken GetColorManagementSystem() const
Sets the name of the color management system to be used for loading and interpreting the color config...
USD_API bool ClearMetadataByDictKey(const TfToken &key, const TfToken &keyPath) const
Clear any authored value identified by key and keyPath at the current EditTarget.
USD_API bool 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...
USD_API void Reload()
Calls SdfLayer::Reload on all layers contributing to this stage, except session layers and sublayers ...
USD_API bool ExportToString(std::string *result, bool addSourceFileComment=true) const
Writes the composite scene as a flattened Usd text representation into the given string.
USD_API void Unload(const SdfPath &path=SdfPath::AbsoluteRootPath())
Modify this stage's load rules to unload the prim and its descendants specified by path.
USD_API void SetFramesPerSecond(double framesPerSecond) const
Sets the stage's framesPerSecond value.
USD_API SdfPathSet FindLoadable(const SdfPath &rootPath=SdfPath::AbsoluteRootPath())
Returns an SdfPathSet of all paths that can be loaded.
USD_API void SetEditTarget(const UsdEditTarget &editTarget)
Set the stage's EditTarget.
static USD_API UsdStageRefPtr Open(const std::string &filePath, InitialLoadSet load=LoadAll)
Attempt to find a matching existing stage in a cache if UsdStageCacheContext objects exist on the sta...
static USD_API void SetColorConfigFallbacks(const SdfAssetPath &colorConfiguration, const TfToken &colorManagementSystem)
Sets the global fallback values of color configuration metadata which includes the 'colorConfiguratio...
USD_API void WriteFallbackPrimTypes()
Writes the fallback prim types defined in the schema registry to the stage as dictionary valued fallb...
UsdInterpolationType
Attribute value interpolation options.
Definition: interpolation.h:46
An asset resolver context allows clients to provide additional data to the resolver for use during re...
USD_API void MuteLayer(const std::string &layerIdentifier)
Mute the layer identified by layerIdentifier.
USD_API void SetColorManagementSystem(const TfToken &cms) const
Sets the name of the color management system used to interpret the color configuration file pointed a...
UsdVariantSets represents the collection of VariantSets that are present on a UsdPrim.
Definition: variantSets.h:222
std::map< double, VtValue > SdfTimeSampleMap
A map from sample times to sample values.
Definition: types.h:295
USD_API SdfLayerHandle GetRootLayer() const
Return this stage's root layer.
bool IsHolding() const
Return true if this value is holding an object of type T, false otherwise.
Definition: value.h:1053
UsdStageLoadRules const & GetLoadRules() const
Return the stage's current UsdStageLoadRules governing payload inclusion.
Definition: stage.h:649
static USD_API PcpVariantFallbackMap GetGlobalVariantFallbacks()
Get the global variant fallback preferences used in new UsdStages.
USD_API UsdInterpolationType GetInterpolationType() const
Returns the interpolation type used during value resolution for all attributes on this stage.
Enable a concrete base class for use with TfWeakPtr.
Definition: weakBase.h:141
USD_API void ClearDefaultPrim()
Clear the default prim layer metadata in this stage's root layer.
char const * GetText() const
Return the text that this token represents.
Definition: token.h:196
Provides a container which may hold any type, and provides introspection and iteration over array typ...
Definition: value.h:166
USD_API UsdAttribute GetAttributeAtPath(const SdfPath &path) const
Return the UsdAttribute at path, or an invalid UsdAttribute if none exists.
This class represents a mask that may be applied to a UsdStage to limit the set of UsdPrim s it popul...
std::map< std::string, std::vector< std::string > > PcpVariantFallbackMap
typedef std::map<std::string, std::vector<std::string>> PcpVariantFallbackMap
Definition: types.h:188
USD_API void SetColorConfiguration(const SdfAssetPath &colorConfig) const
Sets the default color configuration to be used to interpret the per-attribute color-spaces in the co...
Load all loadable prims.
Definition: stage.h:162
Defines a subrange of nodes and layers within a prim's prim index to consider when performing value r...
Definition: resolveTarget.h:73
USD_API UsdEditTarget GetEditTargetForLocalLayer(size_t i)
Return a UsdEditTarget for editing the layer at index i in the layer stack.