All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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 _ComposeSubtreeInParallel(Usd_PrimDataPtr prim);
1817  void _ComposeSubtreesInParallel(
1818  const std::vector<Usd_PrimDataPtr> &prims,
1819  const std::vector<SdfPath> *primIndexPaths = nullptr);
1820 
1821  // Compose subtree rooted at \p prim under \p parent. This function
1822  // ensures that the appropriate prim index is specified for \p prim if
1823  // \p parent is in a prototype.
1824  void _ComposeChildSubtree(Usd_PrimDataPtr prim,
1825  Usd_PrimDataConstPtr parent,
1826  UsdStagePopulationMask const *mask);
1827 
1828  // Compose \p prim's list of children and make any modifications necessary
1829  // to its _children member and the stage's _primMap, including possibly
1830  // instantiating new prims, or destroying existing subtrees of prims. The
1831  // any newly created prims *do not* have their prim index, type, flags, or
1832  // children composed.
1833  //
1834  // Compose only \p prim's direct children if recurse=false. Otherwise
1835  // recompose every descendent of \p prim. Callers that pass recurse=false
1836  // should invoke _ComposeSubtree on any newly created prims to ensure caches
1837  // are correctly populated.
1838  void _ComposeChildren(Usd_PrimDataPtr prim,
1839  UsdStagePopulationMask const *mask, bool recurse);
1840 
1841  // Instantiate a prim instance. There must not already be an instance
1842  // at \p primPath.
1843  Usd_PrimDataPtr _InstantiatePrim(const SdfPath &primPath);
1844 
1845  // Instantiate a prototype prim and sets its parent to pseudoroot.
1846  // There must not already be a prototype at \p primPath.
1847  Usd_PrimDataPtr _InstantiatePrototypePrim(const SdfPath &primPath);
1848 
1849  // For \p prim and all of its descendants, remove from _primMap and empty
1850  // their _children vectors.
1851  void _DestroyPrim(Usd_PrimDataPtr prim);
1852 
1853  // Destroy the prim subtrees rooted at each path in \p paths. \p paths may
1854  // not contain any path that is a descendent of another path in \p paths.
1855  void _DestroyPrimsInParallel(const std::vector<SdfPath>& paths);
1856 
1857  // Invoke _DestroyPrim() on all of \p prim's direct children.
1858  void _DestroyDescendents(Usd_PrimDataPtr prim);
1859 
1860  // Returns true if the object at the given path is a descendant of
1861  // an instance prim, i.e. a prim beneath an instance prim, or a property
1862  // of a prim beneath an instance prim.
1863  bool _IsObjectDescendantOfInstance(const SdfPath& path) const;
1864 
1865  // If the given prim is an instance, returns the corresponding
1866  // prototype prim. Otherwise, returns an invalid prim.
1867  Usd_PrimDataConstPtr _GetPrototypeForInstance(Usd_PrimDataConstPtr p) const;
1868 
1869  // Returns the path of the Usd prim using the prim index at the given path.
1870  SdfPath _GetPrimPathUsingPrimIndexAtPath(const SdfPath& primIndexPath) const;
1871 
1872  // Update stage contents in response to changes in scene description.
1873  void _HandleLayersDidChange(const SdfNotice::LayersDidChangeSentPerLayer &);
1874 
1875  // Update stage contents in response to changes to the asset resolver.
1876  void _HandleResolverDidChange(const ArNotice::ResolverChanged &);
1877 
1878  // Process stage change information stored in _pendingChanges.
1879  // _pendingChanges will be set to nullptr by the end of the function.
1880  void _ProcessPendingChanges();
1881 
1882  // Remove scene description for the prim at \p fullPath in the current edit
1883  // target.
1884  bool _RemovePrim(const SdfPath& fullPath);
1885 
1886  SdfPrimSpecHandle _GetPrimSpec(const SdfPath& fullPath);
1887 
1888  // Find and return the defining spec type for the property spec at the given
1889  // path, or SdfSpecTypeUnknown if none exists. The defining spec type is
1890  // either the builtin definition's spec type, if the indicated property is
1891  // builtin, otherwise it's the strongest authored spec's type if one exists,
1892  // otherwise it's SdfSpecTypeUnknown.
1893  SdfSpecType _GetDefiningSpecType(Usd_PrimDataConstPtr primData,
1894  const TfToken &propName) const;
1895 
1896  // Helper to apply Pcp changes and recompose the scenegraph accordingly,
1897  // given an optional initial set of paths to recompose.
1898  void _Recompose(const PcpChanges &changes);
1899  template <class T>
1900  void _Recompose(const PcpChanges &changes, T *pathsToRecompose);
1901  template <class T>
1902  void _RecomposePrims(T *pathsToRecompose);
1903 
1904  // Helper for _Recompose to find the subtrees that need to be
1905  // fully recomposed and to recompose the name children of the
1906  // parents of these subtrees. Note that [start, finish) must be a
1907  // sorted range of paths with no descendent paths.
1908  template <class Iter>
1909  void _ComputeSubtreesToRecompose(Iter start, Iter finish,
1910  std::vector<Usd_PrimDataPtr>* recompose);
1911 
1912  // return true if the path is valid for load/unload operations.
1913  // This method will emit errors when invalid paths are encountered.
1914  bool _IsValidForLoad(const SdfPath& path) const;
1915  bool _IsValidForUnload(const SdfPath& path) const;
1916 
1917  // Discover all payloads in a given subtree, adding the path of each
1918  // discovered prim index to the \p primIndexPaths set. If specified,
1919  // the corresponding UsdPrim path will be added to the \p usdPrimPaths
1920  // set. The root path will be considered for inclusion in the result set.
1921  //
1922  // Note that some payloads may not be discoverable in until an ancestral
1923  // payload has been included. UsdStage::LoadAndUnload takes this into
1924  // account.
1925  void _DiscoverPayloads(const SdfPath& rootPath,
1926  UsdLoadPolicy policy,
1927  SdfPathSet* primIndexPaths,
1928  bool unloadedOnly = false,
1929  SdfPathSet* usdPrimPaths = nullptr) const;
1930 
1931  // ===================================================================== //
1932  // VALUE RESOLUTION //
1933  // ===================================================================== //
1934  // --------------------------------------------------------------------- //
1935  // Specialized Value Resolution
1936  // --------------------------------------------------------------------- //
1937 
1938  // Helpers for resolving values for metadata fields requiring
1939  // special behaviors.
1940  static SdfSpecifier _GetSpecifier(Usd_PrimDataConstPtr primData);
1941  static TfToken _GetKind(Usd_PrimDataConstPtr primData);
1942  static bool _IsActive(Usd_PrimDataConstPtr primData);
1943 
1944  // Custom is true if it is true anywhere in the stack.
1945  bool _IsCustom(const UsdProperty &prop) const;
1946 
1947  // Variability is determined by the weakest opinion in the stack.
1948  SdfVariability _GetVariability(const UsdProperty &prop) const;
1949 
1950  // Helper functions for resolving asset paths during value resolution.
1951  void _MakeResolvedAssetPaths(UsdTimeCode time, const UsdAttribute &attr,
1952  SdfAssetPath *assetPaths,
1953  size_t numAssetPaths,
1954  bool anchorAssetPathsOnly = false) const;
1955 
1956  void _MakeResolvedAssetPathsValue(UsdTimeCode time, const UsdAttribute &attr,
1957  VtValue *value,
1958  bool anchorAssetPathsOnly = false) const;
1959 
1960  void _MakeResolvedTimeCodes(UsdTimeCode time, const UsdAttribute &attr,
1961  SdfTimeCode *timeCodes,
1962  size_t numTimeCodes) const;
1963 
1964  void _MakeResolvedAttributeValue(UsdTimeCode time, const UsdAttribute &attr,
1965  VtValue *value) const;
1966 
1967  // --------------------------------------------------------------------- //
1968  // Metadata Resolution
1969  // --------------------------------------------------------------------- //
1970 
1971 public:
1972  // Trait that allows us to call the correct version of _GetMetadata for
1973  // types that require type specific value resolution as opposed to just
1974  // strongest opinion. These types also use type specific resolution
1975  // in _GetValue.
1976  template <class T>
1977  struct _HasTypeSpecificResolution {
1978  static const bool value =
1979  std::is_same<T, SdfAssetPath>::value ||
1980  std::is_same<T, VtArray<SdfAssetPath>>::value ||
1981  std::is_same<T, SdfTimeCode>::value ||
1982  std::is_same<T, VtArray<SdfTimeCode>>::value ||
1983  std::is_same<T, SdfTimeSampleMap>::value ||
1984  std::is_same<T, VtDictionary>::value;
1985  };
1986 
1987 private:
1988  // Get metadata for types that do not have type specific value resolution.
1989  template <class T>
1990  typename std::enable_if<!_HasTypeSpecificResolution<T>::value, bool>::type
1991  _GetMetadata(const UsdObject &obj,
1992  const TfToken& fieldName,
1993  const TfToken &keyPath,
1994  bool useFallbacks,
1995  T* result) const;
1996 
1997  // Get metadata for types that do have type specific value resolution.
1998  template <class T>
1999  typename std::enable_if<_HasTypeSpecificResolution<T>::value, bool>::type
2000  _GetMetadata(const UsdObject &obj,
2001  const TfToken& fieldName,
2002  const TfToken &keyPath,
2003  bool useFallbacks,
2004  T* result) const;
2005 
2006  // Get metadata as a dynamically typed VtValue. Will perform type specific
2007  // value resolution if the returned held type requires it.
2008  bool _GetMetadata(const UsdObject &obj,
2009  const TfToken& fieldName,
2010  const TfToken &keyPath,
2011  bool useFallbacks,
2012  VtValue* result) const;
2013 
2014  // Gets a metadata value using only strongest value resolution. It is
2015  // assumed that result is holding a value that does not require type
2016  // specific value resolution.
2017  USD_API
2018  bool _GetStrongestResolvedMetadata(const UsdObject &obj,
2019  const TfToken& fieldName,
2020  const TfToken &keyPath,
2021  bool useFallbacks,
2022  SdfAbstractDataValue* result) const;
2023 
2024  // Gets a metadata value with the type specific value resolution for the
2025  // type applied. This is only implemented for types that
2026  // _HasTypeSpecificResolution.
2027  template <class T>
2028  USD_API
2029  bool _GetTypeSpecificResolvedMetadata(const UsdObject &obj,
2030  const TfToken& fieldName,
2031  const TfToken &keyPath,
2032  bool useFallbacks,
2033  T* result) const;
2034 
2035  template <class Composer>
2036  void _GetAttrTypeImpl(const UsdAttribute &attr,
2037  const TfToken &fieldName,
2038  bool useFallbacks,
2039  Composer *composer) const;
2040 
2041  template <class Composer>
2042  void _GetAttrVariabilityImpl(const UsdAttribute &attr,
2043  bool useFallbacks,
2044  Composer *composer) const;
2045 
2046  template <class Composer>
2047  void _GetPropCustomImpl(const UsdProperty &prop,
2048  bool useFallbacks,
2049  Composer *composer) const;
2050 
2051  template <class Composer>
2052  bool _GetSpecialPropMetadataImpl(const UsdObject &obj,
2053  const TfToken &fieldName,
2054  const TfToken &keyPath,
2055  bool useFallbacks,
2056  Composer *composer) const;
2057  template <class Composer>
2058  bool _GetMetadataImpl(const UsdObject &obj,
2059  const TfToken& fieldName,
2060  const TfToken& keyPath,
2061  bool includeFallbacks,
2062  Composer *composer) const;
2063 
2064  template <class Composer>
2065  bool _GetGeneralMetadataImpl(const UsdObject &obj,
2066  const TfToken& fieldName,
2067  const TfToken& keyPath,
2068  bool includeFallbacks,
2069  Composer *composer) const;
2070 
2071  // NOTE: The "authoredOnly" flag is not yet in use, but when we have
2072  // support for prim-based metadata fallbacks, they should be ignored when
2073  // this flag is set to true.
2074  bool _HasMetadata(const UsdObject &obj, const TfToken& fieldName,
2075  const TfToken &keyPath, bool useFallbacks) const;
2076 
2078  _ListMetadataFields(const UsdObject &obj, bool useFallbacks) const;
2079 
2080  void _GetAllMetadata(const UsdObject &obj,
2081  bool useFallbacks,
2082  UsdMetadataValueMap* result,
2083  bool anchorAssetPathsOnly = false) const;
2084 
2085  // --------------------------------------------------------------------- //
2086  // Default & TimeSample Resolution
2087  // --------------------------------------------------------------------- //
2088 
2089  void _GetResolveInfo(const UsdAttribute &attr,
2090  UsdResolveInfo *resolveInfo,
2091  const UsdTimeCode *time = nullptr) const;
2092 
2093  template <class T> struct _ExtraResolveInfo;
2094 
2095  template <class T>
2096  void _GetResolveInfo(const UsdAttribute &attr,
2097  UsdResolveInfo *resolveInfo,
2098  const UsdTimeCode *time = nullptr,
2099  _ExtraResolveInfo<T> *extraInfo = nullptr) const;
2100 
2101  template <class T> struct _ResolveInfoResolver;
2102  struct _PropertyStackResolver;
2103 
2104  template <class Resolver>
2105  void _GetResolvedValueImpl(const UsdProperty &prop,
2106  Resolver *resolver,
2107  const UsdTimeCode *time = nullptr) const;
2108 
2109  bool _GetValue(UsdTimeCode time, const UsdAttribute &attr,
2110  VtValue* result) const;
2111 
2112  template <class T>
2113  bool _GetValue(UsdTimeCode time, const UsdAttribute &attr,
2114  T* result) const;
2115 
2116  template <class T>
2117  bool _GetValueImpl(UsdTimeCode time, const UsdAttribute &attr,
2118  Usd_InterpolatorBase* interpolator,
2119  T* value) const;
2120 
2122  _GetLayerWithStrongestValue(
2123  UsdTimeCode time, const UsdAttribute &attr) const;
2124 
2125 
2126 
2127  USD_API
2128  bool _GetValueFromResolveInfo(const UsdResolveInfo &info,
2129  UsdTimeCode time, const UsdAttribute &attr,
2130  VtValue* result) const;
2131 
2132  template <class T>
2133  USD_API
2134  bool _GetValueFromResolveInfo(const UsdResolveInfo &info,
2135  UsdTimeCode time, const UsdAttribute &attr,
2136  T* result) const;
2137 
2138  template <class T>
2139  bool _GetValueFromResolveInfoImpl(const UsdResolveInfo &info,
2140  UsdTimeCode time, const UsdAttribute &attr,
2141  Usd_InterpolatorBase* interpolator,
2142  T* value) const;
2143 
2144  // --------------------------------------------------------------------- //
2145  // Specialized Time Sample I/O
2146  // --------------------------------------------------------------------- //
2147 
2154  bool _GetTimeSamplesInInterval(const UsdAttribute &attr,
2155  const GfInterval& interval,
2156  std::vector<double>* times) const;
2157 
2158  bool _GetTimeSamplesInIntervalFromResolveInfo(
2159  const UsdResolveInfo &info,
2160  const UsdAttribute &attr,
2161  const GfInterval& interval,
2162  std::vector<double>* times) const;
2163 
2164  size_t _GetNumTimeSamples(const UsdAttribute &attr) const;
2165 
2166  size_t _GetNumTimeSamplesFromResolveInfo(const UsdResolveInfo &info,
2167  const UsdAttribute &attr) const;
2168 
2172  bool _GetBracketingTimeSamples(const UsdAttribute &attr,
2173  double desiredTime,
2174  bool authoredOnly,
2175  double* lower,
2176  double* upper,
2177  bool* hasSamples) const;
2178 
2179  bool _GetBracketingTimeSamplesFromResolveInfo(const UsdResolveInfo &info,
2180  const UsdAttribute &attr,
2181  double desiredTime,
2182  bool authoredOnly,
2183  double* lower,
2184  double* upper,
2185  bool* hasSamples) const;
2186 
2187  bool _ValueMightBeTimeVarying(const UsdAttribute &attr) const;
2188 
2189  bool _ValueMightBeTimeVaryingFromResolveInfo(const UsdResolveInfo &info,
2190  const UsdAttribute &attr) const;
2191 
2192  void _RegisterPerLayerNotices();
2193  void _RegisterResolverChangeNotice();
2194 
2195 private:
2196 
2197  // The 'pseudo root' prim.
2198  Usd_PrimDataPtr _pseudoRoot;
2199 
2200  // The stage's root layer.
2201  SdfLayerRefPtr _rootLayer;
2202 
2203  // Every UsdStage has an implicit, in-memory session layer.
2204  // This is to allow for runtime overrides such as variant selections.
2205  SdfLayerRefPtr _sessionLayer;
2206 
2207  // The stage's EditTarget.
2208  UsdEditTarget _editTarget;
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&#39;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 unit of scene description that you combine with other units of scene description to form a shot...
Definition: layer.h:96
Load no loadable prims.
Definition: stage.h:161
USD_API void SetStartTimeCode(double)
Sets the stage&#39;s start timeCode.
USD_API UsdPrimRange Traverse()
Traverse the active, loaded, defined, non-abstract prims on this stage depth-first.
static USD_API void GetColorConfigFallbacks(SdfAssetPath *colorConfiguration, TfToken *colorManagementSystem)
Returns the global fallback values of &#39;colorConfiguration&#39; and &#39;colorManagementSystem&#39;.
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 UsdPrim GetPseudoRoot() const
Return the stage&#39;s &quot;pseudo-root&quot; prim, whose name is defined by Usd.
PcpPrimIndex is an index of the all sites of scene description that contribute opinions to a specific...
Definition: primIndex.h:75
T const & UncheckedGet() const
Returns a const reference to the held object if the held object is of type T.
Definition: value.h:1090
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&#39;s root layer.
USD_API SdfAssetPath GetColorConfiguration() const
Returns the default color configuration used to interpret the per- attribute color-spaces in the comp...
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
The fully-typed container for a field value in an SdfAbstractData.
Definition: abstractData.h:519
USD_API UsdPrim OverridePrim(const SdfPath &path)
Attempt to ensure a UsdPrim at path exists on this stage.
USD_API UsdInterpolationType GetInterpolationType() const
Returns the interpolation type used during value resolution for all attributes 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 void LoadAndUnload(const SdfPathSet &loadSet, const SdfPathSet &unloadSet, UsdLoadPolicy policy=UsdLoadWithDescendants)
Unload and load the given path sets.
USD_API double GetFramesPerSecond() const
Returns the stage&#39;s framesPerSecond value.
USD_API const UsdEditTarget & GetEditTarget() const
Return the stage&#39;s EditTarget.
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.
PcpCache is the context required to make requests of the Pcp composition algorithm and cache the resu...
Definition: cache.h:93
bool IsHolding() const
Return true if this value is holding an object of type T, false otherwise.
Definition: value.h:1062
static USD_API bool IsSupportedFile(const std::string &filePath)
Indicates whether the specified file is supported by UsdStage.
USD_API UsdPrim GetPrimAtPath(const SdfPath &path) const
Return the UsdPrim at path, or an invalid UsdPrim if none exists.
The outermost container for scene description, which owns and presents composed prims as a scenegraph...
Definition: stage.h:145
UsdStageLoadRules const & GetLoadRules() const
Return the stage&#39;s current UsdStageLoadRules governing payload inclusion.
Definition: stage.h:647
USD_API void SetTimeCodesPerSecond(double timeCodesPerSecond) const
Sets the stage&#39;s timeCodesPerSecond value.
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 UsdPrim GetDefaultPrim() const
Return the root UsdPrim on this stage whose name is the root layer&#39;s defaultPrim metadata&#39;s value...
USD_API void Save()
Calls SdfLayer::Save on all dirty layers contributing to this stage except session layers and sublaye...
USD_API SdfLayerHandle GetRootLayer() const
Return this stage&#39;s root layer.
USD_API bool IsLayerMuted(const std::string &layerIdentifier) const
Returns true if the layer specified by layerIdentifier is muted in this cache, false otherwise...
The base class for all API schemas.
Container for information about the source of an attribute&#39;s value, i.e.
Definition: resolveInfo.h:68
Scenegraph object for authoring and retrieving numeric, string, and array valued data, sampled over time.
Definition: attribute.h:176
USD_API UsdProperty GetPropertyAtPath(const SdfPath &path) const
Return the UsdProperty at path, or an invalid UsdProperty if none exists.
SdfHandle is a smart ptr that calls IsDormant() on the pointed-to object as an extra expiration check...
USD_API bool HasLocalLayer(const SdfLayerHandle &layer) const
Return true if layer is one of the layers in this stage&#39;s local, root layerStack. ...
Basic Sdf data types.
USD_API std::vector< UsdPrim > GetPrototypes() const
Returns all native instancing prototype prims.
Enable a concrete base class for use with TfRefPtr.
Definition: refBase.h:71
USD_API bool ClearMetadata(const TfToken &key) const
Clear the value of stage metadatum key, if the stage&#39;s current UsdEditTarget is the root or session l...
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...
UsdStagePopulationMask GetPopulationMask() const
Return this stage&#39;s population mask.
Definition: stage.h:664
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:87
USD_API SdfLayerHandleVector GetLayerStack(bool includeSessionLayers=true) const
Return this stage&#39;s local layers in strong-to-weak order.
USD_API double GetEndTimeCode() const
Returns the stage&#39;s end timeCode.
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 HasDefaultPrim() const
Return true if this stage&#39;s root layer has an authored opinion for the default prim layer metadata...
USD_API void UnmuteLayer(const std::string &layerIdentifier)
Unmute the layer identified by layerIdentifier if it had previously been muted.
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.
Value type that represents a time code.
Definition: timeCode.h:44
A UsdVariantSet represents a single VariantSet in USD (e.g.
Definition: variantSets.h:56
USD_API void SetFramesPerSecond(double framesPerSecond) const
Sets the stage&#39;s framesPerSecond value.
Represent a time value, which may be either numeric, holding a double value, or a sentinel value UsdT...
Definition: timeCode.h:85
USD_API bool RemovePrim(const SdfPath &path)
Remove all scene description for the given path and its subtree in the current UsdEditTarget.
USD_API bool HasAuthoredTimeCodeRange() const
Returns true if the stage has both start and end timeCodes authored in the session layer or the root ...
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:444
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.
UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a &quot;Prim&quot; as ...
Definition: prim.h:132
USD_API UsdAttribute GetAttributeAtPath(const SdfPath &path) const
Return the UsdAttribute at path, or an invalid UsdAttribute if none exists.
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:122
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
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
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:288
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 UsdRelationship GetRelationshipAtPath(const SdfPath &path) const
Return the UsdAttribute at path, or an invalid UsdAttribute if none exists.
VT_API std::string GetTypeName() const
Return the type name of the held typeid.
USD_API UsdObject GetObjectAtPath(const SdfPath &path) const
Return the UsdObject at path, or an invalid UsdObject if none exists.
A UsdRelationship creates dependencies between scenegraph objects by allowing a prim to target other ...
Definition: relationship.h:128
USD_API double GetStartTimeCode() const
Returns the stage&#39;s start timeCode.
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&#39;s population mask and recompose the stage.
SdfVariability
An enum that identifies variability types for attributes.
Definition: types.h:179
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 void SetEndTimeCode(double)
Sets the stage&#39;s end timeCode.
UsdLoadPolicy
Controls UsdStage::Load() and UsdPrim::Load() behavior regarding whether or not descendant prims are ...
Definition: common.h:116
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
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&#39;s load rules to load the prim at path, its ancestors, and all of its descendants if...
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...
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
SdfSpecType
An enum that specifies the type of an object.
Definition: types.h:91
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
static SDF_API const SdfPath & AbsoluteRootPath()
The absolute path representing the top of the namespace hierarchy.
USD_API double GetTimeCodesPerSecond() const
Returns the stage&#39;s timeCodesPerSecond value.
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. ...
USD_API const std::vector< std::string > & GetMutedLayers() const
Returns a vector of all layers that have been muted on this stage.
USD_API void Reload()
Calls SdfLayer::Reload on all layers contributing to this stage, except session layers and sublayers ...
USD_API void Unload(const SdfPath &path=SdfPath::AbsoluteRootPath())
Modify this stage&#39;s load rules to unload the prim and its descendants specified by path...
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&#39;s EditTarget.
USD_API TfToken GetColorManagementSystem() const
Sets the name of the color management system to be used for loading and interpreting the color config...
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 &#39;colorConfiguratio...
USD_API SdfLayerHandle GetSessionLayer() const
Return this stage&#39;s root session layer.
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 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 SdfLayerRefPtr Flatten(bool addSourceFileComment=true) const
Returns a single, anonymous, merged layer for this composite scene.
USD_API std::string ResolveIdentifierToEditTarget(std::string const &identifier) const
Resolve the given identifier using this stage&#39;s ArResolverContext and the layer of its GetEditTarget(...
UsdVariantSets represents the collection of VariantSets that are present on a UsdPrim.
Definition: variantSets.h:222
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...
std::map< double, VtValue > SdfTimeSampleMap
A map from sample times to sample values.
Definition: types.h:296
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 PcpVariantFallbackMap GetGlobalVariantFallbacks()
Get the global variant fallback preferences used in new UsdStages.
Enable a concrete base class for use with TfWeakPtr.
Definition: weakBase.h:141
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...
USD_API void ClearDefaultPrim()
Clear the default prim layer metadata in this stage&#39;s root layer.
Provides a container which may hold any type, and provides introspection and iteration over array typ...
Definition: value.h:168
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&lt;std::string, std::vector&lt;std::string&gt;&gt; PcpVariantFallbackMap
Definition: types.h:188
USD_API ArResolverContext GetPathResolverContext() const
Return the path resolver context for all path resolution during composition of this stage...
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...
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.
bool SetMetadata(const TfToken &key, const T &value) const
Set the value of Stage metadatum key to value, if the stage&#39;s current UsdEditTarget is the root or se...
Definition: stage.h:2314
char const * GetText() const
Return the text that this token represents.
Definition: token.h:196