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/spin_rw_mutex.h>
58 
59 #include <functional>
60 #include <string>
61 #include <memory>
62 #include <unordered_map>
63 #include <utility>
64 
65 PXR_NAMESPACE_OPEN_SCOPE
66 
67 
68 class ArResolverContext;
69 class GfInterval;
71 class Usd_ClipCache;
72 class Usd_InstanceCache;
73 class Usd_InstanceChanges;
74 class Usd_InterpolatorBase;
75 class UsdResolveInfo;
76 class Usd_Resolver;
77 class UsdPrim;
78 class UsdPrimRange;
79 
80 SDF_DECLARE_HANDLES(SdfLayer);
81 
145 class UsdStage : public TfRefBase, public TfWeakBase {
146 public:
147 
148  // --------------------------------------------------------------------- //
152  // --------------------------------------------------------------------- //
153 
159  {
162  };
163 
174  //
186  USD_API
187  static UsdStageRefPtr
188  CreateNew(const std::string& identifier,
189  InitialLoadSet load = LoadAll);
191  USD_API
192  static UsdStageRefPtr
193  CreateNew(const std::string& identifier,
194  const SdfLayerHandle& sessionLayer,
195  InitialLoadSet load = LoadAll);
197  USD_API
198  static UsdStageRefPtr
199  CreateNew(const std::string& identifier,
200  const SdfLayerHandle& sessionLayer,
201  const ArResolverContext& pathResolverContext,
202  InitialLoadSet load = LoadAll);
204  USD_API
205  static UsdStageRefPtr
206  CreateNew(const std::string& identifier,
207  const ArResolverContext& pathResolverContext,
208  InitialLoadSet load = LoadAll);
209 
227  USD_API
228  static UsdStageRefPtr
231  USD_API
232  static UsdStageRefPtr
233  CreateInMemory(const std::string& identifier,
234  InitialLoadSet load = LoadAll);
236  USD_API
237  static UsdStageRefPtr
238  CreateInMemory(const std::string& identifier,
239  const ArResolverContext& pathResolverContext,
240  InitialLoadSet load = LoadAll);
242  USD_API
243  static UsdStageRefPtr
244  CreateInMemory(const std::string& identifier,
245  const SdfLayerHandle &sessionLayer,
246  InitialLoadSet load = LoadAll);
248  USD_API
249  static UsdStageRefPtr
250  CreateInMemory(const std::string& identifier,
251  const SdfLayerHandle &sessionLayer,
252  const ArResolverContext& pathResolverContext,
253  InitialLoadSet load = LoadAll);
254 
270  USD_API
271  static UsdStageRefPtr
272  Open(const std::string& filePath, InitialLoadSet load = LoadAll);
274  USD_API
275  static UsdStageRefPtr
276  Open(const std::string& filePath,
277  const ArResolverContext& pathResolverContext,
278  InitialLoadSet load = LoadAll);
279 
297  USD_API
298  static UsdStageRefPtr
299  OpenMasked(const std::string &filePath,
300  UsdStagePopulationMask const &mask,
301  InitialLoadSet load = LoadAll);
303  USD_API
304  static UsdStageRefPtr
305  OpenMasked(const std::string &filePath,
306  const ArResolverContext &pathResolverContext,
307  UsdStagePopulationMask const &mask,
308  InitialLoadSet load = LoadAll);
309 
338  USD_API
339  static UsdStageRefPtr
340  Open(const SdfLayerHandle& rootLayer,
341  InitialLoadSet load=LoadAll);
343  USD_API
344  static UsdStageRefPtr
345  Open(const SdfLayerHandle& rootLayer,
346  const SdfLayerHandle& sessionLayer,
347  InitialLoadSet load=LoadAll);
349  USD_API
350  static UsdStageRefPtr
351  Open(const SdfLayerHandle& rootLayer,
352  const ArResolverContext& pathResolverContext,
353  InitialLoadSet load=LoadAll);
355  USD_API
356  static UsdStageRefPtr
357  Open(const SdfLayerHandle& rootLayer,
358  const SdfLayerHandle& sessionLayer,
359  const ArResolverContext& pathResolverContext,
360  InitialLoadSet load=LoadAll);
361 
382  USD_API
383  static UsdStageRefPtr
384  OpenMasked(const SdfLayerHandle& rootLayer,
385  const UsdStagePopulationMask &mask,
386  InitialLoadSet load=LoadAll);
388  USD_API
389  static UsdStageRefPtr
390  OpenMasked(const SdfLayerHandle& rootLayer,
391  const SdfLayerHandle& sessionLayer,
392  const UsdStagePopulationMask &mask,
393  InitialLoadSet load=LoadAll);
395  USD_API
396  static UsdStageRefPtr
397  OpenMasked(const SdfLayerHandle& rootLayer,
398  const ArResolverContext& pathResolverContext,
399  const UsdStagePopulationMask &mask,
400  InitialLoadSet load=LoadAll);
402  USD_API
403  static UsdStageRefPtr
404  OpenMasked(const SdfLayerHandle& rootLayer,
405  const SdfLayerHandle& sessionLayer,
406  const ArResolverContext& pathResolverContext,
407  const UsdStagePopulationMask &mask,
408  InitialLoadSet load=LoadAll);
409 
410  USD_API
411  virtual ~UsdStage();
412 
430  USD_API
431  void Reload();
432 
441  USD_API
442  static bool
443  IsSupportedFile(const std::string& filePath);
444 
446 
447  // --------------------------------------------------------------------- //
456 
464  USD_API
465  void Save();
466 
474  USD_API
475  void SaveSessionLayers();
476 
478 
479  // --------------------------------------------------------------------- //
525 
527  USD_API
529 
535  USD_API
536  static void
538 
540 
541  // --------------------------------------------------------------------- //
570  // --------------------------------------------------------------------- //
571 
579  USD_API
582 
588  USD_API
589  void Unload(const SdfPath& path=SdfPath::AbsoluteRootPath());
590 
602  USD_API
603  void LoadAndUnload(const SdfPathSet &loadSet, const SdfPathSet &unloadSet,
605 
616  USD_API
617  SdfPathSet GetLoadSet();
618 
638  USD_API
639  SdfPathSet FindLoadable(
640  const SdfPath& rootPath = SdfPath::AbsoluteRootPath());
641 
648  return _loadRules;
649  }
650 
660  USD_API
661  void SetLoadRules(UsdStageLoadRules const &rules);
662 
665  return _populationMask;
666  }
667 
669  USD_API
670  void SetPopulationMask(UsdStagePopulationMask const &mask);
671 
683  USD_API
685  std::function<bool (UsdRelationship const &)> const &relPred = nullptr,
686  std::function<bool (UsdAttribute const &)> const &attrPred = nullptr);
687 
689 
690  // --------------------------------------------------------------------- //
699  // --------------------------------------------------------------------- //
700 
710  USD_API
711  UsdPrim GetPseudoRoot() const;
712 
719  USD_API
720  UsdPrim GetDefaultPrim() const;
721 
729  USD_API
730  void SetDefaultPrim(const UsdPrim &prim);
731 
739  USD_API
740  void ClearDefaultPrim();
741 
749  USD_API
750  bool HasDefaultPrim() const;
751 
761  USD_API
762  UsdPrim GetPrimAtPath(const SdfPath &path) const;
763 
788  USD_API
789  UsdObject GetObjectAtPath(const SdfPath &path) const;
790 
799  USD_API
800  UsdProperty GetPropertyAtPath(const SdfPath &path) const;
801 
810  USD_API
811  UsdAttribute GetAttributeAtPath(const SdfPath &path) const;
812 
821  USD_API
822  UsdRelationship GetRelationshipAtPath(const SdfPath &path) const;
823 private:
824  // Return the primData object at \p path.
825  Usd_PrimDataConstPtr _GetPrimDataAtPath(const SdfPath &path) const;
826  Usd_PrimDataPtr _GetPrimDataAtPath(const SdfPath &path);
827 
828  // Return the primData object at \p path. If \p path indicates a prim
829  // beneath an instance, return the primData object for the corresponding
830  // prim in the instance's prototype.
831  Usd_PrimDataConstPtr
832  _GetPrimDataAtPathOrInPrototype(const SdfPath &path) const;
833 
835  std::vector<UsdPrim>
836  _GetInstancesForPrototype(const UsdPrim& prototype) const;
837 
838 public:
839 
856  USD_API
858 
863  USD_API
864  UsdPrimRange Traverse(const Usd_PrimFlagsPredicate &predicate);
865 
870  USD_API
872 
891  USD_API
892  UsdPrim OverridePrim(const SdfPath &path);
893 
917  USD_API
918  UsdPrim DefinePrim(const SdfPath &path,
919  const TfToken &typeName=TfToken());
920 
933  USD_API
934  UsdPrim CreateClassPrim(const SdfPath &rootPrimPath);
935 
957  USD_API
958  bool RemovePrim(const SdfPath& path);
959 
961 
962  // --------------------------------------------------------------------- //
966  // --------------------------------------------------------------------- //
967 
969  USD_API
970  SdfLayerHandle GetSessionLayer() const;
971 
973  USD_API
974  SdfLayerHandle GetRootLayer() const;
975 
980  USD_API
982 
992  USD_API
993  std::string
994  ResolveIdentifierToEditTarget(std::string const &identifier) const;
995 
1002  USD_API
1003  SdfLayerHandleVector GetLayerStack(bool includeSessionLayers=true) const;
1004 
1016  USD_API
1017  SdfLayerHandleVector GetUsedLayers(bool includeClipLayers=true) const;
1018 
1021  USD_API
1022  bool HasLocalLayer(const SdfLayerHandle &layer) const;
1023 
1025  USD_API
1026  const UsdEditTarget &GetEditTarget() const;
1027 
1031  USD_API
1033 
1037  USD_API
1038  UsdEditTarget GetEditTargetForLocalLayer(const SdfLayerHandle &layer);
1039 
1046  USD_API
1047  void SetEditTarget(const UsdEditTarget &editTarget);
1048 
1056 #if AR_VERSION == 1
1057 #else
1064 #endif
1069  USD_API
1085  void MuteLayer(const std::string &layerIdentifier);
1086 
1089  USD_API
1090  void UnmuteLayer(const std::string &layerIdentifier);
1091 
1099  USD_API
1100  void MuteAndUnmuteLayers(const std::vector<std::string> &muteLayers,
1101  const std::vector<std::string> &unmuteLayers);
1102 
1104  USD_API
1105  const std::vector<std::string>& GetMutedLayers() const;
1106 
1111  USD_API
1112  bool IsLayerMuted(const std::string& layerIdentifier) const;
1113 
1115 
1116  // --------------------------------------------------------------------- //
1120  // --------------------------------------------------------------------- //
1121  // Future Work:
1122  // * Flatten sub-trees or individual prims
1123  // * Allow flattening of local LayerStack
1124  // * Move Flatten into a free-function to ensure it doesn't rely on
1125  // Stage internals.
1126 
1134  USD_API
1135  bool Export(const std::string &filename,
1136  bool addSourceFileComment=true,
1137  const SdfLayer::FileFormatArguments &args =
1139 
1147  USD_API
1148  bool ExportToString(std::string *result,
1149  bool addSourceFileComment=true) const;
1150 
1177  USD_API
1178  SdfLayerRefPtr Flatten(bool addSourceFileComment=true) const;
1180 
1181 public:
1182  // --------------------------------------------------------------------- //
1190  // --------------------------------------------------------------------- //
1191 
1203  template <class T>
1204  bool GetMetadata(const TfToken &key, T *value) const;
1206  USD_API
1207  bool GetMetadata(const TfToken &key, VtValue *value) const;
1208 
1215  USD_API
1216  bool HasMetadata(const TfToken &key) const;
1217 
1226  USD_API
1227  bool HasAuthoredMetadata(const TfToken &key) const;
1228 
1237  template<typename T>
1238  bool SetMetadata(const TfToken &key, const T &value) const;
1240  USD_API
1241  bool SetMetadata(const TfToken &key, const VtValue &value) const;
1242 
1251  USD_API
1252  bool ClearMetadata(const TfToken &key) const;
1253 
1269  template<typename T>
1270  bool GetMetadataByDictKey(const TfToken& key, const TfToken &keyPath,
1271  T* value) const;
1273  USD_API
1274  bool GetMetadataByDictKey(
1275  const TfToken& key, const TfToken &keyPath, VtValue *value) const;
1276 
1287  USD_API
1288  bool HasMetadataDictKey(
1289  const TfToken& key, const TfToken &keyPath) const;
1290 
1299  USD_API
1301  const TfToken& key, const TfToken &keyPath) const;
1302 
1314  template<typename T>
1315  bool SetMetadataByDictKey(const TfToken& key, const TfToken &keyPath,
1316  const T& value) const;
1318  USD_API
1319  bool SetMetadataByDictKey(
1320  const TfToken& key, const TfToken &keyPath, const VtValue& value) const;
1321 
1333  USD_API
1335  const TfToken& key, const TfToken& keyPath) const;
1336 
1355  USD_API
1356  void WriteFallbackPrimTypes();
1357 
1359 
1360  // --------------------------------------------------------------------- //
1367  // --------------------------------------------------------------------- //
1371  USD_API
1372  double GetStartTimeCode() const;
1373 
1380  USD_API
1381  void SetStartTimeCode(double);
1382 
1386  USD_API
1387  double GetEndTimeCode() const;
1388 
1395  USD_API
1396  void SetEndTimeCode(double);
1397 
1400  USD_API
1401  bool HasAuthoredTimeCodeRange() const;
1402 
1418  USD_API
1419  double GetTimeCodesPerSecond() const;
1420 
1429  USD_API
1430  void SetTimeCodesPerSecond(double timeCodesPerSecond) const;
1431 
1441  USD_API
1442  double GetFramesPerSecond() const;
1443 
1452  USD_API
1453  void SetFramesPerSecond(double framesPerSecond) const;
1454 
1456 
1457  // --------------------------------------------------------------------- //
1503  // --------------------------------------------------------------------- //
1504 
1510  USD_API
1511  void SetColorConfiguration(const SdfAssetPath &colorConfig) const;
1512 
1517  USD_API
1519 
1524  USD_API
1525  void SetColorManagementSystem(const TfToken &cms) const;
1526 
1531  USD_API
1533 
1545  USD_API
1546  static void GetColorConfigFallbacks(SdfAssetPath *colorConfiguration,
1547  TfToken *colorManagementSystem);
1548 
1562  USD_API
1563  static void
1564  SetColorConfigFallbacks(const SdfAssetPath &colorConfiguration,
1565  const TfToken &colorManagementSystem);
1566 
1568 
1569  // --------------------------------------------------------------------- //
1576  // --------------------------------------------------------------------- //
1577 
1582  USD_API
1583  void SetInterpolationType(UsdInterpolationType interpolationType);
1584 
1587  USD_API
1589 
1591 
1592  // --------------------------------------------------------------------- //
1597  // --------------------------------------------------------------------- //
1598 
1600  USD_API
1601  std::vector<UsdPrim> GetPrototypes() const;
1602 
1604 
1605 private:
1606  struct _IncludePayloadsPredicate;
1607 
1608  // --------------------------------------------------------------------- //
1609  // Stage Construction & Initialization
1610  // --------------------------------------------------------------------- //
1611 
1612  UsdStage(const SdfLayerRefPtr& rootLayer,
1613  const SdfLayerRefPtr& sessionLayer,
1614  const ArResolverContext& pathResolverContext,
1615  const UsdStagePopulationMask& mask,
1616  InitialLoadSet load);
1617 
1618  // Helper for Open() overloads -- searches and publishes to bound caches.
1619  template <class... Args>
1620  static UsdStageRefPtr _OpenImpl(InitialLoadSet load, Args const &... args);
1621 
1622  // Releases resources used by this stage.
1623  void _Close();
1624 
1625  // Common ref ptr initialization, called by public, static constructors.
1626  //
1627  // This method will either return a valid refptr (if the stage is correctly
1628  // initialized) or it will return a null ref pointer, deleting the
1629  // raw stage pointer in the process.
1630  static UsdStageRefPtr
1631  _InstantiateStage(const SdfLayerRefPtr &rootLayer,
1632  const SdfLayerRefPtr &sessionLayer,
1633  const ArResolverContext &pathResolverContext,
1634  const UsdStagePopulationMask &mask,
1635  InitialLoadSet load);
1636 
1637  // --------------------------------------------------------------------- //
1638  // Spec Existence & Definition Helpers
1639  // --------------------------------------------------------------------- //
1640 
1641  SdfPropertySpecHandleVector
1642  _GetPropertyStack(const UsdProperty &prop, UsdTimeCode time) const;
1643 
1644  SdfPropertySpecHandle
1645  _GetSchemaPropertySpec(const UsdPrim &prim, const TfToken &propName) const;
1646 
1647  SdfPropertySpecHandle
1648  _GetSchemaPropertySpec(const UsdProperty &prop) const;
1649 
1650  template <class PropType>
1652  _GetSchemaPropertySpec(const UsdProperty &prop) const;
1653 
1654  SdfAttributeSpecHandle
1655  _GetSchemaAttributeSpec(const UsdAttribute &attr) const;
1656 
1657  SdfRelationshipSpecHandle
1658  _GetSchemaRelationshipSpec(const UsdRelationship &rel) const;
1659 
1660  SdfPrimSpecHandle
1661  _CreatePrimSpecForEditing(const UsdPrim& prim);
1662 
1663  template <class PropType>
1665  _CreatePropertySpecForEditing(const UsdProperty &prop);
1666 
1667  SdfPropertySpecHandle
1668  _CreatePropertySpecForEditing(const UsdProperty &prop);
1669 
1670  SdfAttributeSpecHandle
1671  _CreateAttributeSpecForEditing(const UsdAttribute &attr);
1672 
1673  SdfRelationshipSpecHandle
1674  _CreateRelationshipSpecForEditing(const UsdRelationship &rel);
1675 
1676  // Check if the given path is valid to use with the prim creation API,
1677  // like DefinePrim. If it is valid, returns (true, GetPrimAtPath(path)).
1678  // Otherwise, returns (false, UsdPrim()).
1679  std::pair<bool, UsdPrim>
1680  _IsValidPathForCreatingPrim(const SdfPath &path) const;
1681 
1682  // Validates that editing a specified prim is allowed. If editing is not
1683  // allowed, issues a coding error like "Cannot <operation> ..." and
1684  // returns false. Otherwise, returns true.
1685  bool _ValidateEditPrim(const UsdPrim &prim, const char* operation) const;
1686  bool _ValidateEditPrimAtPath(const SdfPath &primPath,
1687  const char* operation) const;
1688 
1689  UsdPrim _DefinePrim(const SdfPath &path, const TfToken &typeName);
1690 
1691  bool _RemoveProperty(const SdfPath& path);
1692 
1693  UsdProperty _FlattenProperty(const UsdProperty &srcProp,
1694  const UsdPrim &dstParent,
1695  const TfToken &dstName);
1696 
1697  // --------------------------------------------------------------------- //
1698  // Value & Metadata Authoring
1699  // --------------------------------------------------------------------- //
1700 
1701  // Trait that allows us to call the correct versions of _SetValue and
1702  // _SetMetadata for types whose values need to be mapped when written to
1703  // different edit targets.
1704  template <class T>
1705  struct _IsEditTargetMappable {
1706  static const bool value =
1707  std::is_same<T, SdfTimeCode>::value ||
1708  std::is_same<T, VtArray<SdfTimeCode>>::value ||
1709  std::is_same<T, SdfTimeSampleMap>::value ||
1710  std::is_same<T, VtDictionary>::value;
1711  };
1712 
1713  // Set value for types that don't need to be mapped for edit targets.
1714  template <class T>
1715  typename std::enable_if<!_IsEditTargetMappable<T>::value, bool>::type
1716  _SetValue(
1717  UsdTimeCode time, const UsdAttribute &attr, const T &newValue);
1718 
1719  // Set value for types that do need to be mapped for edit targets.
1720  template <class T>
1721  typename std::enable_if<_IsEditTargetMappable<T>::value, bool>::type
1722  _SetValue(
1723  UsdTimeCode time, const UsdAttribute &attr, const T &newValue);
1724 
1725  // Set value for dynamically typed VtValue. Will map the value across edit
1726  // targets if the held value type supports it.
1727  bool _SetValue(
1728  UsdTimeCode time, const UsdAttribute &attr, const VtValue &newValue);
1729 
1730  template <class T>
1731  bool _SetEditTargetMappedValue(
1732  UsdTimeCode time, const UsdAttribute &attr, const T &newValue);
1733 
1734  template <class T>
1735  bool _SetValueImpl(
1736  UsdTimeCode time, const UsdAttribute &attr, const T& value);
1737 
1738  bool _ClearValue(UsdTimeCode time, const UsdAttribute &attr);
1739 
1740  // Set metadata for types that don't need to be mapped across edit targets.
1741  template <class T>
1742  typename std::enable_if<!_IsEditTargetMappable<T>::value, bool>::type
1743  _SetMetadata(const UsdObject &object, const TfToken& key,
1744  const TfToken &keyPath, const T& value);
1745 
1746  // Set metadata for types that do need to be mapped for edit targets.
1747  template <class T>
1748  typename std::enable_if<_IsEditTargetMappable<T>::value, bool>::type
1749  _SetMetadata(const UsdObject &object, const TfToken& key,
1750  const TfToken &keyPath, const T& value);
1751 
1752  // Set metadata for dynamically typed VtValue. Will map the value across
1753  // edit targets if the held value type supports it.
1754  USD_API
1755  bool _SetMetadata(const UsdObject &object,
1756  const TfToken& key,
1757  const TfToken &keyPath,
1758  const VtValue& value);
1759 
1760  template <class T>
1761  bool _SetEditTargetMappedMetadata(
1762  const UsdObject &obj, const TfToken& fieldName,
1763  const TfToken &keyPath, const T &newValue);
1764 
1765  template <class T>
1766  bool _SetMetadataImpl(
1767  const UsdObject &obj, const TfToken& fieldName,
1768  const TfToken &keyPath, const T &value);
1769 
1770  bool _ClearMetadata(const UsdObject &obj, const TfToken& fieldName,
1771  const TfToken &keyPath=TfToken());
1772 
1773  // --------------------------------------------------------------------- //
1774  // Misc Internal Helpers
1775  // --------------------------------------------------------------------- //
1776 
1777  // Pcp helpers.
1778  PcpCache const *_GetPcpCache() const { return _cache.get(); }
1779  PcpCache *_GetPcpCache() { return _cache.get(); }
1780 
1781  // Returns the PrimIndex, using the read-only PcpCache API. We expect prims
1782  // to be composed during initial stage composition, so this method should
1783  // not be used in that context.
1784  const PcpPrimIndex* _GetPcpPrimIndex(const SdfPath& primPath) const;
1785 
1786  // Helper to report pcp errors.
1787  void _ReportPcpErrors(const PcpErrorVector &errors,
1788  const std::string &context) const;
1789  void _ReportErrors(const PcpErrorVector &errors,
1790  const std::vector<std::string>& otherErrors,
1791  const std::string &context) const;
1792 
1793  // --------------------------------------------------------------------- //
1794  // Scenegraph Composition & Change Processing
1795  // --------------------------------------------------------------------- //
1796 
1797  // Compose the prim indexes in the subtrees rooted at the paths in
1798  // \p primIndexPaths. If \p instanceChanges is given, returns
1799  // changes to prototypes and instances due to the discovery of new instances
1800  // during composition.
1801  void _ComposePrimIndexesInParallel(
1802  const std::vector<SdfPath>& primIndexPaths,
1803  const std::string& context,
1804  Usd_InstanceChanges* instanceChanges = nullptr);
1805 
1806  // Recompose the subtree rooted at \p prim: compose its type, flags, and
1807  // list of children, then invoke _ComposeSubtree on all its children.
1808  void _ComposeSubtree(
1809  Usd_PrimDataPtr prim, Usd_PrimDataConstPtr parent,
1810  UsdStagePopulationMask const *mask,
1811  const SdfPath &primIndexPath = SdfPath());
1812  void _ComposeSubtreeImpl(
1813  Usd_PrimDataPtr prim, Usd_PrimDataConstPtr parent,
1814  UsdStagePopulationMask const *mask,
1815  const SdfPath &primIndexPath = SdfPath());
1816  void _ComposeSubtreesInParallel(
1817  const std::vector<Usd_PrimDataPtr> &prims,
1818  const std::vector<SdfPath> *primIndexPaths = nullptr);
1819 
1820  // Compose subtree rooted at \p prim under \p parent. This function
1821  // ensures that the appropriate prim index is specified for \p prim if
1822  // \p parent is in a prototype.
1823  void _ComposeChildSubtree(Usd_PrimDataPtr prim,
1824  Usd_PrimDataConstPtr parent,
1825  UsdStagePopulationMask const *mask);
1826 
1827  // Compose \p prim's list of children and make any modifications necessary
1828  // to its _children member and the stage's _primMap, including possibly
1829  // instantiating new prims, or destroying existing subtrees of prims. The
1830  // any newly created prims *do not* have their prim index, type, flags, or
1831  // children composed.
1832  //
1833  // Compose only \p prim's direct children if recurse=false. Otherwise
1834  // recompose every descendent of \p prim. Callers that pass recurse=false
1835  // should invoke _ComposeSubtree on any newly created prims to ensure caches
1836  // are correctly populated.
1837  void _ComposeChildren(Usd_PrimDataPtr prim,
1838  UsdStagePopulationMask const *mask, bool recurse);
1839 
1840  // Instantiate a prim instance. There must not already be an instance
1841  // at \p primPath.
1842  Usd_PrimDataPtr _InstantiatePrim(const SdfPath &primPath);
1843 
1844  // Instantiate a prototype prim and sets its parent to pseudoroot.
1845  // There must not already be a prototype at \p primPath.
1846  Usd_PrimDataPtr _InstantiatePrototypePrim(const SdfPath &primPath);
1847 
1848  // For \p prim and all of its descendants, remove from _primMap and empty
1849  // their _children vectors.
1850  void _DestroyPrim(Usd_PrimDataPtr prim);
1851 
1852  // Destroy the prim subtrees rooted at each path in \p paths. \p paths may
1853  // not contain any path that is a descendent of another path in \p paths.
1854  void _DestroyPrimsInParallel(const std::vector<SdfPath>& paths);
1855 
1856  // Invoke _DestroyPrim() on all of \p prim's direct children.
1857  void _DestroyDescendents(Usd_PrimDataPtr prim);
1858 
1859  // Returns true if the object at the given path is a descendant of
1860  // an instance prim, i.e. a prim beneath an instance prim, or a property
1861  // of a prim beneath an instance prim.
1862  bool _IsObjectDescendantOfInstance(const SdfPath& path) const;
1863 
1864  // If the given prim is an instance, returns the corresponding
1865  // prototype prim. Otherwise, returns an invalid prim.
1866  Usd_PrimDataConstPtr _GetPrototypeForInstance(Usd_PrimDataConstPtr p) const;
1867 
1868  // Returns the path of the Usd prim using the prim index at the given path.
1869  SdfPath _GetPrimPathUsingPrimIndexAtPath(const SdfPath& primIndexPath) const;
1870 
1871  // Update stage contents in response to changes in scene description.
1872  void _HandleLayersDidChange(const SdfNotice::LayersDidChangeSentPerLayer &);
1873 
1874  // Update stage contents in response to changes to the asset resolver.
1875  void _HandleResolverDidChange(const ArNotice::ResolverChanged &);
1876 
1877  // Process stage change information stored in _pendingChanges.
1878  // _pendingChanges will be set to nullptr by the end of the function.
1879  void _ProcessPendingChanges();
1880 
1881  // Remove scene description for the prim at \p fullPath in the current edit
1882  // target.
1883  bool _RemovePrim(const SdfPath& fullPath);
1884 
1885  SdfPrimSpecHandle _GetPrimSpec(const SdfPath& fullPath);
1886 
1887  // Find and return the defining spec type for the property spec at the given
1888  // path, or SdfSpecTypeUnknown if none exists. The defining spec type is
1889  // either the builtin definition's spec type, if the indicated property is
1890  // builtin, otherwise it's the strongest authored spec's type if one exists,
1891  // otherwise it's SdfSpecTypeUnknown.
1892  SdfSpecType _GetDefiningSpecType(Usd_PrimDataConstPtr primData,
1893  const TfToken &propName) const;
1894 
1895  // Helper to apply Pcp changes and recompose the scenegraph accordingly,
1896  // given an optional initial set of paths to recompose.
1897  void _Recompose(const PcpChanges &changes);
1898  template <class T>
1899  void _Recompose(const PcpChanges &changes, T *pathsToRecompose);
1900  template <class T>
1901  void _RecomposePrims(T *pathsToRecompose);
1902 
1903  // Helper for _Recompose to find the subtrees that need to be
1904  // fully recomposed and to recompose the name children of the
1905  // parents of these subtrees. Note that [start, finish) must be a
1906  // sorted range of paths with no descendent paths.
1907  template <class Iter>
1908  void _ComputeSubtreesToRecompose(Iter start, Iter finish,
1909  std::vector<Usd_PrimDataPtr>* recompose);
1910 
1911  // return true if the path is valid for load/unload operations.
1912  // This method will emit errors when invalid paths are encountered.
1913  bool _IsValidForLoad(const SdfPath& path) const;
1914  bool _IsValidForUnload(const SdfPath& path) const;
1915 
1916  // Discover all payloads in a given subtree, adding the path of each
1917  // discovered prim index to the \p primIndexPaths set. If specified,
1918  // the corresponding UsdPrim path will be added to the \p usdPrimPaths
1919  // set. The root path will be considered for inclusion in the result set.
1920  //
1921  // Note that some payloads may not be discoverable in until an ancestral
1922  // payload has been included. UsdStage::LoadAndUnload takes this into
1923  // account.
1924  void _DiscoverPayloads(const SdfPath& rootPath,
1925  UsdLoadPolicy policy,
1926  SdfPathSet* primIndexPaths,
1927  bool unloadedOnly = false,
1928  SdfPathSet* usdPrimPaths = nullptr) const;
1929 
1930  // ===================================================================== //
1931  // VALUE RESOLUTION //
1932  // ===================================================================== //
1933  // --------------------------------------------------------------------- //
1934  // Specialized Value Resolution
1935  // --------------------------------------------------------------------- //
1936 
1937  // Helpers for resolving values for metadata fields requiring
1938  // special behaviors.
1939  static SdfSpecifier _GetSpecifier(Usd_PrimDataConstPtr primData);
1940  static TfToken _GetKind(Usd_PrimDataConstPtr primData);
1941  static bool _IsActive(Usd_PrimDataConstPtr primData);
1942 
1943  // Custom is true if it is true anywhere in the stack.
1944  bool _IsCustom(const UsdProperty &prop) const;
1945 
1946  // Variability is determined by the weakest opinion in the stack.
1947  SdfVariability _GetVariability(const UsdProperty &prop) const;
1948 
1949  // Helper functions for resolving asset paths during value resolution.
1950  void _MakeResolvedAssetPaths(UsdTimeCode time, const UsdAttribute &attr,
1951  SdfAssetPath *assetPaths,
1952  size_t numAssetPaths,
1953  bool anchorAssetPathsOnly = false) const;
1954 
1955  void _MakeResolvedAssetPathsValue(UsdTimeCode time, const UsdAttribute &attr,
1956  VtValue *value,
1957  bool anchorAssetPathsOnly = false) const;
1958 
1959  void _MakeResolvedTimeCodes(UsdTimeCode time, const UsdAttribute &attr,
1960  SdfTimeCode *timeCodes,
1961  size_t numTimeCodes) const;
1962 
1963  void _MakeResolvedAttributeValue(UsdTimeCode time, const UsdAttribute &attr,
1964  VtValue *value) const;
1965 
1966  // --------------------------------------------------------------------- //
1967  // Metadata Resolution
1968  // --------------------------------------------------------------------- //
1969 
1970 public:
1971  // Trait that allows us to call the correct version of _GetMetadata for
1972  // types that require type specific value resolution as opposed to just
1973  // strongest opinion. These types also use type specific resolution
1974  // in _GetValue.
1975  template <class T>
1976  struct _HasTypeSpecificResolution {
1977  static const bool value =
1978  std::is_same<T, SdfAssetPath>::value ||
1979  std::is_same<T, VtArray<SdfAssetPath>>::value ||
1980  std::is_same<T, SdfTimeCode>::value ||
1981  std::is_same<T, VtArray<SdfTimeCode>>::value ||
1982  std::is_same<T, SdfTimeSampleMap>::value ||
1983  std::is_same<T, VtDictionary>::value;
1984  };
1985 
1986 private:
1987  // Get metadata for types that do not have type specific value resolution.
1988  template <class T>
1989  typename std::enable_if<!_HasTypeSpecificResolution<T>::value, bool>::type
1990  _GetMetadata(const UsdObject &obj,
1991  const TfToken& fieldName,
1992  const TfToken &keyPath,
1993  bool useFallbacks,
1994  T* result) const;
1995 
1996  // Get metadata for types that do have type specific value resolution.
1997  template <class T>
1998  typename std::enable_if<_HasTypeSpecificResolution<T>::value, bool>::type
1999  _GetMetadata(const UsdObject &obj,
2000  const TfToken& fieldName,
2001  const TfToken &keyPath,
2002  bool useFallbacks,
2003  T* result) const;
2004 
2005  // Get metadata as a dynamically typed VtValue. Will perform type specific
2006  // value resolution if the returned held type requires it.
2007  bool _GetMetadata(const UsdObject &obj,
2008  const TfToken& fieldName,
2009  const TfToken &keyPath,
2010  bool useFallbacks,
2011  VtValue* result) const;
2012 
2013  // Gets a metadata value using only strongest value resolution. It is
2014  // assumed that result is holding a value that does not require type
2015  // specific value resolution.
2016  USD_API
2017  bool _GetStrongestResolvedMetadata(const UsdObject &obj,
2018  const TfToken& fieldName,
2019  const TfToken &keyPath,
2020  bool useFallbacks,
2021  SdfAbstractDataValue* result) const;
2022 
2023  // Gets a metadata value with the type specific value resolution for the
2024  // type applied. This is only implemented for types that
2025  // _HasTypeSpecificResolution.
2026  template <class T>
2027  USD_API
2028  bool _GetTypeSpecificResolvedMetadata(const UsdObject &obj,
2029  const TfToken& fieldName,
2030  const TfToken &keyPath,
2031  bool useFallbacks,
2032  T* result) const;
2033 
2034  template <class Composer>
2035  void _GetAttrTypeImpl(const UsdAttribute &attr,
2036  const TfToken &fieldName,
2037  bool useFallbacks,
2038  Composer *composer) const;
2039 
2040  template <class Composer>
2041  void _GetAttrVariabilityImpl(const UsdAttribute &attr,
2042  bool useFallbacks,
2043  Composer *composer) const;
2044 
2045  template <class Composer>
2046  void _GetPropCustomImpl(const UsdProperty &prop,
2047  bool useFallbacks,
2048  Composer *composer) const;
2049 
2050  template <class Composer>
2051  bool _GetSpecialPropMetadataImpl(const UsdObject &obj,
2052  const TfToken &fieldName,
2053  const TfToken &keyPath,
2054  bool useFallbacks,
2055  Composer *composer) const;
2056  template <class Composer>
2057  bool _GetMetadataImpl(const UsdObject &obj,
2058  const TfToken& fieldName,
2059  const TfToken& keyPath,
2060  bool includeFallbacks,
2061  Composer *composer) const;
2062 
2063  template <class Composer>
2064  bool _GetGeneralMetadataImpl(const UsdObject &obj,
2065  const TfToken& fieldName,
2066  const TfToken& keyPath,
2067  bool includeFallbacks,
2068  Composer *composer) const;
2069 
2070  // NOTE: The "authoredOnly" flag is not yet in use, but when we have
2071  // support for prim-based metadata fallbacks, they should be ignored when
2072  // this flag is set to true.
2073  bool _HasMetadata(const UsdObject &obj, const TfToken& fieldName,
2074  const TfToken &keyPath, bool useFallbacks) const;
2075 
2077  _ListMetadataFields(const UsdObject &obj, bool useFallbacks) const;
2078 
2079  void _GetAllMetadata(const UsdObject &obj,
2080  bool useFallbacks,
2081  UsdMetadataValueMap* result,
2082  bool anchorAssetPathsOnly = false) const;
2083 
2084  // --------------------------------------------------------------------- //
2085  // Default & TimeSample Resolution
2086  // --------------------------------------------------------------------- //
2087 
2088  void _GetResolveInfo(const UsdAttribute &attr,
2089  UsdResolveInfo *resolveInfo,
2090  const UsdTimeCode *time = nullptr) const;
2091 
2092  template <class T> struct _ExtraResolveInfo;
2093 
2094  template <class T>
2095  void _GetResolveInfo(const UsdAttribute &attr,
2096  UsdResolveInfo *resolveInfo,
2097  const UsdTimeCode *time = nullptr,
2098  _ExtraResolveInfo<T> *extraInfo = nullptr) const;
2099 
2100  template <class T> struct _ResolveInfoResolver;
2101  struct _PropertyStackResolver;
2102 
2103  template <class Resolver>
2104  void _GetResolvedValueImpl(const UsdProperty &prop,
2105  Resolver *resolver,
2106  const UsdTimeCode *time = nullptr) const;
2107 
2108  bool _GetValue(UsdTimeCode time, const UsdAttribute &attr,
2109  VtValue* result) const;
2110 
2111  template <class T>
2112  bool _GetValue(UsdTimeCode time, const UsdAttribute &attr,
2113  T* result) const;
2114 
2115  template <class T>
2116  bool _GetValueImpl(UsdTimeCode time, const UsdAttribute &attr,
2117  Usd_InterpolatorBase* interpolator,
2118  T* value) const;
2119 
2121  _GetLayerWithStrongestValue(
2122  UsdTimeCode time, const UsdAttribute &attr) const;
2123 
2124 
2125 
2126  USD_API
2127  bool _GetValueFromResolveInfo(const UsdResolveInfo &info,
2128  UsdTimeCode time, const UsdAttribute &attr,
2129  VtValue* result) const;
2130 
2131  template <class T>
2132  USD_API
2133  bool _GetValueFromResolveInfo(const UsdResolveInfo &info,
2134  UsdTimeCode time, const UsdAttribute &attr,
2135  T* result) const;
2136 
2137  template <class T>
2138  bool _GetValueFromResolveInfoImpl(const UsdResolveInfo &info,
2139  UsdTimeCode time, const UsdAttribute &attr,
2140  Usd_InterpolatorBase* interpolator,
2141  T* value) const;
2142 
2143  // --------------------------------------------------------------------- //
2144  // Specialized Time Sample I/O
2145  // --------------------------------------------------------------------- //
2146 
2153  bool _GetTimeSamplesInInterval(const UsdAttribute &attr,
2154  const GfInterval& interval,
2155  std::vector<double>* times) const;
2156 
2157  bool _GetTimeSamplesInIntervalFromResolveInfo(
2158  const UsdResolveInfo &info,
2159  const UsdAttribute &attr,
2160  const GfInterval& interval,
2161  std::vector<double>* times) const;
2162 
2163  size_t _GetNumTimeSamples(const UsdAttribute &attr) const;
2164 
2165  size_t _GetNumTimeSamplesFromResolveInfo(const UsdResolveInfo &info,
2166  const UsdAttribute &attr) const;
2167 
2171  bool _GetBracketingTimeSamples(const UsdAttribute &attr,
2172  double desiredTime,
2173  bool authoredOnly,
2174  double* lower,
2175  double* upper,
2176  bool* hasSamples) const;
2177 
2178  bool _GetBracketingTimeSamplesFromResolveInfo(const UsdResolveInfo &info,
2179  const UsdAttribute &attr,
2180  double desiredTime,
2181  bool authoredOnly,
2182  double* lower,
2183  double* upper,
2184  bool* hasSamples) const;
2185 
2186  bool _ValueMightBeTimeVarying(const UsdAttribute &attr) const;
2187 
2188  bool _ValueMightBeTimeVaryingFromResolveInfo(const UsdResolveInfo &info,
2189  const UsdAttribute &attr) const;
2190 
2191  void _RegisterPerLayerNotices();
2192  void _RegisterResolverChangeNotice();
2193 
2194 private:
2195 
2196  // The 'pseudo root' prim.
2197  Usd_PrimDataPtr _pseudoRoot;
2198 
2199  // The stage's root layer.
2200  SdfLayerRefPtr _rootLayer;
2201 
2202  // Every UsdStage has an implicit, in-memory session layer.
2203  // This is to allow for runtime overrides such as variant selections.
2204  SdfLayerRefPtr _sessionLayer;
2205 
2206  // The stage's EditTarget.
2207  UsdEditTarget _editTarget;
2208  bool _editTargetIsLocalLayer;
2209 
2210  std::unique_ptr<PcpCache> _cache;
2211  std::unique_ptr<Usd_ClipCache> _clipCache;
2212  std::unique_ptr<Usd_InstanceCache> _instanceCache;
2213 
2214  TfHashMap<TfToken, TfToken, TfHash> _invalidPrimTypeToFallbackMap;
2215 
2216  size_t _usedLayersRevision;
2217 
2218  // A map from Path to Prim, for fast random access.
2219  typedef TfHashMap<
2220  SdfPath, Usd_PrimDataIPtr, SdfPath::Hash> PathToNodeMap;
2221  PathToNodeMap _primMap;
2222  mutable boost::optional<tbb::spin_rw_mutex> _primMapMutex;
2223 
2224  // The interpolation type used for all attributes on the stage.
2225  UsdInterpolationType _interpolationType;
2226 
2227  typedef std::vector<
2228  std::pair<SdfLayerHandle, TfNotice::Key> > _LayerAndNoticeKeyVec;
2229  _LayerAndNoticeKeyVec _layersAndNoticeKeys;
2230  size_t _lastChangeSerialNumber;
2231 
2232  TfNotice::Key _resolverChangeKey;
2233 
2234  // Data for pending change processing.
2235  class _PendingChanges;
2236  _PendingChanges* _pendingChanges;
2237 
2238  boost::optional<WorkDispatcher> _dispatcher;
2239 
2240  // To provide useful aggregation of malloc stats, we bill everything
2241  // for this stage - from all access points - to this tag.
2242  char const *_mallocTagID;
2243 
2244  // The state used when instantiating the stage.
2245  const InitialLoadSet _initialLoadSet;
2246 
2247  // The population mask that applies to this stage.
2248  UsdStagePopulationMask _populationMask;
2249 
2250  // The load rules that apply to this stage.
2251  UsdStageLoadRules _loadRules;
2252 
2253  bool _isClosingStage;
2254  bool _isWritingFallbackPrimTypes;
2255 
2256  friend class UsdAPISchemaBase;
2257  friend class UsdAttribute;
2258  friend class UsdAttributeQuery;
2259  friend class UsdEditTarget;
2260  friend class UsdInherits;
2261  friend class UsdObject;
2262  friend class UsdPrim;
2263  friend class UsdProperty;
2264  friend class UsdRelationship;
2265  friend class UsdSpecializes;
2266  friend class UsdVariantSet;
2267  friend class UsdVariantSets;
2268  friend class Usd_FlattenAccess;
2269  friend class Usd_PcpCacheAccess;
2270  friend class Usd_PrimData;
2271  friend class Usd_StageOpenRequest;
2272  template <class T> friend struct Usd_AttrGetValueHelper;
2273  friend struct Usd_AttrGetUntypedValueHelper;
2274  template <class RefsOrPayloadsEditorType, class RefsOrPayloadsProxyType>
2275  friend struct Usd_ListEditImpl;
2276 };
2277 
2278 // UsdObject's typed metadata query relies on this specialization being
2279 // externally visible and exporting the primary template does not
2280 // automatically export this specialization.
2281 template <>
2282 USD_API
2283 bool
2284 UsdStage::_GetTypeSpecificResolvedMetadata(const UsdObject &obj,
2285  const TfToken& fieldName,
2286  const TfToken &keyPath,
2287  bool useFallbacks,
2288  SdfTimeSampleMap* result) const;
2289 
2290 template<typename T>
2291 bool
2292 UsdStage::GetMetadata(const TfToken& key, T* value) const
2293 {
2294  VtValue result;
2295  if (!GetMetadata(key, &result)){
2296  return false;
2297  }
2298 
2299  if (result.IsHolding<T>()){
2300  *value = result.UncheckedGet<T>();
2301  return true;
2302  } else {
2303  TF_CODING_ERROR("Requested type %s for stage metadatum %s does not"
2304  " match retrieved type %s",
2305  ArchGetDemangled<T>().c_str(),
2306  key.GetText(),
2307  result.GetTypeName().c_str());
2308  return false;
2309  }
2310 }
2311 
2312 template<typename T>
2313 bool
2314 UsdStage::SetMetadata(const TfToken& key, const T& value) const
2315 {
2316  VtValue in(value);
2317  return SetMetadata(key, in);
2318 }
2319 
2320 template<typename T>
2321 bool
2322 UsdStage::GetMetadataByDictKey(const TfToken& key, const TfToken &keyPath,
2323  T* value) const
2324 {
2325  VtValue result;
2326  if (!GetMetadataByDictKey(key, keyPath, &result)){
2327  return false;
2328  }
2329 
2330  if (result.IsHolding<T>()){
2331  *value = result.UncheckedGet<T>();
2332  return true;
2333  } else {
2334  TF_CODING_ERROR("Requested type %s for stage metadatum %s[%s] does not"
2335  " match retrieved type %s",
2336  ArchGetDemangled<T>().c_str(),
2337  key.GetText(),
2338  keyPath.GetText(),
2339  result.GetTypeName().c_str());
2340  return false;
2341  }
2342 }
2343 
2344 template<typename T>
2345 bool
2346 UsdStage::SetMetadataByDictKey(const TfToken& key, const TfToken &keyPath,
2347  const T& value) const
2348 {
2349  VtValue in(value);
2350  return SetMetadataByDictKey(key, keyPath, in);
2351 }
2352 
2353 // Get metadata for types that do not have type specific value resolution.
2354 template <class T>
2355 typename std::enable_if<
2356  !UsdStage::_HasTypeSpecificResolution<T>::value, bool>::type
2357 UsdStage::_GetMetadata(const UsdObject &obj,
2358  const TfToken& fieldName,
2359  const TfToken &keyPath,
2360  bool useFallbacks,
2361  T* result) const
2362 {
2363  // Since these types don't have type specific value resolution, we can just
2364  // get the strongest metadata value and be done.
2365  SdfAbstractDataTypedValue<T> out(result);
2366  return _GetStrongestResolvedMetadata(
2367  obj, fieldName, keyPath, useFallbacks, &out);
2368 }
2369 
2370 // Get metadata for types that do have type specific value resolution.
2371 template <class T>
2372 typename std::enable_if<
2373  UsdStage::_HasTypeSpecificResolution<T>::value, bool>::type
2374 UsdStage::_GetMetadata(const UsdObject &obj,
2375  const TfToken& fieldName,
2376  const TfToken &keyPath,
2377  bool useFallbacks,
2378  T* result) const
2379 {
2380  // Call the templated type specifice resolved metadata implementation that
2381  // will only be implemented for types that support it.
2382  return _GetTypeSpecificResolvedMetadata(
2383  obj, fieldName, keyPath, useFallbacks, result);
2384 }
2385 
2386 
2387 // Set metadata for types that don't need to be mapped across edit targets.
2388 template <class T>
2389 typename std::enable_if<!UsdStage::_IsEditTargetMappable<T>::value, bool>::type
2390 UsdStage::_SetMetadata(const UsdObject &object, const TfToken& key,
2391  const TfToken &keyPath, const T& value)
2392 {
2393  // Since we know that we don't need to map the value for edit targets,
2394  // we can just type erase the value and set the metadata as is.
2396  return _SetMetadataImpl<SdfAbstractDataConstValue>(
2397  object, key, keyPath, in);
2398 }
2399 
2400 // Set metadata for types that do need to be mapped for edit targets.
2401 template <class T>
2402 typename std::enable_if<UsdStage::_IsEditTargetMappable<T>::value, bool>::type
2403 UsdStage::_SetMetadata(const UsdObject &object, const TfToken& key,
2404  const TfToken &keyPath, const T& value)
2405 {
2406  return _SetEditTargetMappedMetadata(object, key, keyPath, value);
2407 }
2408 
2409 
2410 PXR_NAMESPACE_CLOSE_SCOPE
2411 
2412 #endif //PXR_USD_USD_STAGE_H
2413 
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:161
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:75
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.
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:2314
The fully-typed container for a field value in an SdfAbstractData.
Definition: abstractData.h:540
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:394
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:2292
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:2346
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:145
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:664
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:445
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:132
InitialLoadSet
Specifies the initial set of prims to load when opening a UsdStage.
Definition: stage.h:158
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.
T const & UncheckedGet() const
Returns a const reference to the held object if the held object is of type T.
Definition: value.h:1077
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:2322
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:1049
UsdStageLoadRules const & GetLoadRules() const
Return the stage's current UsdStageLoadRules governing payload inclusion.
Definition: stage.h:647
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:160
USD_API UsdEditTarget GetEditTargetForLocalLayer(size_t i)
Return a UsdEditTarget for editing the layer at index i in the layer stack.