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  // Helper to obtain a malloc tag string for this stage.
2248  inline char const *_GetMallocTagId() const;
2249 
2250 private:
2251 
2252  // The 'pseudo root' prim.
2253  Usd_PrimDataPtr _pseudoRoot;
2254 
2255  // The stage's root layer.
2256  SdfLayerRefPtr _rootLayer;
2257 
2258  // Every UsdStage has an implicit, in-memory session layer.
2259  // This is to allow for runtime overrides such as variant selections.
2260  SdfLayerRefPtr _sessionLayer;
2261 
2262  // The stage's EditTarget.
2263  UsdEditTarget _editTarget;
2264  bool _editTargetIsLocalLayer;
2265 
2266  std::unique_ptr<PcpCache> _cache;
2267  std::unique_ptr<Usd_ClipCache> _clipCache;
2268  std::unique_ptr<Usd_InstanceCache> _instanceCache;
2269 
2270  TfHashMap<TfToken, TfToken, TfHash> _invalidPrimTypeToFallbackMap;
2271 
2272  size_t _usedLayersRevision;
2273 
2274  // A concurrent map from Path to Prim, for fast random access.
2275  struct _TbbHashEq {
2276  inline bool equal(SdfPath const &l, SdfPath const &r) const {
2277  return l == r;
2278  }
2279  inline size_t hash(SdfPath const &path) const {
2280  return path.GetHash();
2281  }
2282  };
2283  using PathToNodeMap = tbb::concurrent_hash_map<
2284  SdfPath, Usd_PrimDataIPtr, _TbbHashEq>;
2285  PathToNodeMap _primMap;
2286 
2287  // The interpolation type used for all attributes on the stage.
2288  UsdInterpolationType _interpolationType;
2289 
2290  typedef std::vector<
2291  std::pair<SdfLayerHandle, TfNotice::Key> > _LayerAndNoticeKeyVec;
2292  _LayerAndNoticeKeyVec _layersAndNoticeKeys;
2293  size_t _lastChangeSerialNumber;
2294 
2295  TfNotice::Key _resolverChangeKey;
2296 
2297  // Data for pending change processing.
2298  class _PendingChanges;
2299  _PendingChanges* _pendingChanges;
2300 
2301  boost::optional<WorkDispatcher> _dispatcher;
2302 
2303  // To provide useful aggregation of malloc stats, we bill everything
2304  // for this stage - from all access points - to this tag.
2305  std::unique_ptr<std::string> _mallocTagID;
2306 
2307  // The state used when instantiating the stage.
2308  const InitialLoadSet _initialLoadSet;
2309 
2310  // The population mask that applies to this stage.
2311  UsdStagePopulationMask _populationMask;
2312 
2313  // The load rules that apply to this stage.
2314  UsdStageLoadRules _loadRules;
2315 
2316  bool _isClosingStage;
2317  bool _isWritingFallbackPrimTypes;
2318 
2319  friend class UsdAPISchemaBase;
2320  friend class UsdAttribute;
2321  friend class UsdAttributeQuery;
2322  friend class UsdEditTarget;
2323  friend class UsdInherits;
2324  friend class UsdObject;
2325  friend class UsdPrim;
2326  friend class UsdProperty;
2327  friend class UsdRelationship;
2328  friend class UsdSpecializes;
2329  friend class UsdVariantSet;
2330  friend class UsdVariantSets;
2331  friend class Usd_FlattenAccess;
2332  friend class Usd_PcpCacheAccess;
2333  friend class Usd_PrimData;
2334  friend class Usd_StageOpenRequest;
2335  template <class T> friend struct Usd_AttrGetValueHelper;
2336  friend struct Usd_AttrGetUntypedValueHelper;
2337  template <class RefsOrPayloadsEditorType, class RefsOrPayloadsProxyType>
2338  friend struct Usd_ListEditImpl;
2339 };
2340 
2341 // UsdObject's typed metadata query relies on this specialization being
2342 // externally visible and exporting the primary template does not
2343 // automatically export this specialization.
2344 template <>
2345 USD_API
2346 bool
2347 UsdStage::_GetTypeSpecificResolvedMetadata(const UsdObject &obj,
2348  const TfToken& fieldName,
2349  const TfToken &keyPath,
2350  bool useFallbacks,
2351  SdfTimeSampleMap* result) const;
2352 
2353 template<typename T>
2354 bool
2355 UsdStage::GetMetadata(const TfToken& key, T* value) const
2356 {
2357  VtValue result;
2358  if (!GetMetadata(key, &result)){
2359  return false;
2360  }
2361 
2362  if (result.IsHolding<T>()){
2363  *value = result.UncheckedGet<T>();
2364  return true;
2365  } else {
2366  TF_CODING_ERROR("Requested type %s for stage metadatum %s does not"
2367  " match retrieved type %s",
2368  ArchGetDemangled<T>().c_str(),
2369  key.GetText(),
2370  result.GetTypeName().c_str());
2371  return false;
2372  }
2373 }
2374 
2375 template<typename T>
2376 bool
2377 UsdStage::SetMetadata(const TfToken& key, const T& value) const
2378 {
2379  VtValue in(value);
2380  return SetMetadata(key, in);
2381 }
2382 
2383 template<typename T>
2384 bool
2385 UsdStage::GetMetadataByDictKey(const TfToken& key, const TfToken &keyPath,
2386  T* value) const
2387 {
2388  VtValue result;
2389  if (!GetMetadataByDictKey(key, keyPath, &result)){
2390  return false;
2391  }
2392 
2393  if (result.IsHolding<T>()){
2394  *value = result.UncheckedGet<T>();
2395  return true;
2396  } else {
2397  TF_CODING_ERROR("Requested type %s for stage metadatum %s[%s] does not"
2398  " match retrieved type %s",
2399  ArchGetDemangled<T>().c_str(),
2400  key.GetText(),
2401  keyPath.GetText(),
2402  result.GetTypeName().c_str());
2403  return false;
2404  }
2405 }
2406 
2407 template<typename T>
2408 bool
2409 UsdStage::SetMetadataByDictKey(const TfToken& key, const TfToken &keyPath,
2410  const T& value) const
2411 {
2412  VtValue in(value);
2413  return SetMetadataByDictKey(key, keyPath, in);
2414 }
2415 
2416 // Get metadata for types that do not have type specific value resolution.
2417 template <class T>
2418 typename std::enable_if<
2419  !UsdStage::_HasTypeSpecificResolution<T>::value, bool>::type
2420 UsdStage::_GetMetadata(const UsdObject &obj,
2421  const TfToken& fieldName,
2422  const TfToken &keyPath,
2423  bool useFallbacks,
2424  T* result) const
2425 {
2426  // Since these types don't have type specific value resolution, we can just
2427  // get the strongest metadata value and be done.
2428  SdfAbstractDataTypedValue<T> out(result);
2429  return _GetStrongestResolvedMetadata(
2430  obj, fieldName, keyPath, useFallbacks, &out);
2431 }
2432 
2433 // Get metadata for types that do have type specific value resolution.
2434 template <class T>
2435 typename std::enable_if<
2436  UsdStage::_HasTypeSpecificResolution<T>::value, bool>::type
2437 UsdStage::_GetMetadata(const UsdObject &obj,
2438  const TfToken& fieldName,
2439  const TfToken &keyPath,
2440  bool useFallbacks,
2441  T* result) const
2442 {
2443  // Call the templated type specifice resolved metadata implementation that
2444  // will only be implemented for types that support it.
2445  return _GetTypeSpecificResolvedMetadata(
2446  obj, fieldName, keyPath, useFallbacks, result);
2447 }
2448 
2449 
2450 // Set metadata for types that don't need to be mapped across edit targets.
2451 template <class T>
2452 typename std::enable_if<!UsdStage::_IsEditTargetMappable<T>::value, bool>::type
2453 UsdStage::_SetMetadata(const UsdObject &object, const TfToken& key,
2454  const TfToken &keyPath, const T& value)
2455 {
2456  // Since we know that we don't need to map the value for edit targets,
2457  // we can just type erase the value and set the metadata as is.
2459  return _SetMetadataImpl<SdfAbstractDataConstValue>(
2460  object, key, keyPath, in);
2461 }
2462 
2463 // Set metadata for types that do need to be mapped for edit targets.
2464 template <class T>
2465 typename std::enable_if<UsdStage::_IsEditTargetMappable<T>::value, bool>::type
2466 UsdStage::_SetMetadata(const UsdObject &object, const TfToken& key,
2467  const TfToken &keyPath, const T& value)
2468 {
2469  return _SetEditTargetMappedMetadata(object, key, keyPath, value);
2470 }
2471 
2472 
2473 PXR_NAMESPACE_CLOSE_SCOPE
2474 
2475 #endif //PXR_USD_USD_STAGE_H
2476 
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:2377
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:2355
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:2409
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:123
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:179
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:2385
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:91
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:296
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.