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 USD_STAGE_H
25 #define 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"
33 #include "pxr/usd/usd/interpolation.h"
34 #include "pxr/usd/usd/schemaRegistry.h"
35 #include "pxr/usd/usd/stageLoadRules.h"
36 #include "pxr/usd/usd/stagePopulationMask.h"
37 #include "pxr/usd/usd/prim.h"
38 
39 #include "pxr/base/tf/declarePtrs.h"
40 #include "pxr/base/tf/hashmap.h"
41 #include "pxr/base/tf/weakBase.h"
42 
43 #include "pxr/usd/sdf/declareHandles.h"
44 #include "pxr/usd/sdf/notice.h"
45 #include "pxr/usd/sdf/path.h"
46 #include "pxr/usd/sdf/types.h"
47 #include "pxr/usd/pcp/cache.h"
48 #include "pxr/base/vt/value.h"
49 #include "pxr/base/work/arenaDispatcher.h"
50 
51 #include <boost/optional.hpp>
52 
53 #include <tbb/concurrent_vector.h>
54 #include <tbb/concurrent_unordered_set.h>
55 #include <tbb/spin_rw_mutex.h>
56 
57 #include <functional>
58 #include <string>
59 #include <memory>
60 #include <unordered_map>
61 #include <utility>
62 
63 PXR_NAMESPACE_OPEN_SCOPE
64 
65 
66 class ArResolverContext;
67 class GfInterval;
69 class Usd_ClipCache;
70 class Usd_InstanceCache;
71 class Usd_InstanceChanges;
72 class Usd_InterpolatorBase;
73 class UsdResolveInfo;
74 class Usd_Resolver;
75 class UsdPrimRange;
76 
77 SDF_DECLARE_HANDLES(SdfLayer);
78 
142 class UsdStage : public TfRefBase, public TfWeakBase {
143 public:
144 
145  // --------------------------------------------------------------------- //
149  // --------------------------------------------------------------------- //
150 
156  {
159  };
160 
171  //
181  USD_API
182  static UsdStageRefPtr
183  CreateNew(const std::string& identifier,
184  InitialLoadSet load = LoadAll);
186  USD_API
187  static UsdStageRefPtr
188  CreateNew(const std::string& identifier,
189  const SdfLayerHandle& sessionLayer,
190  InitialLoadSet load = LoadAll);
192  USD_API
193  static UsdStageRefPtr
194  CreateNew(const std::string& identifier,
195  const SdfLayerHandle& sessionLayer,
196  const ArResolverContext& pathResolverContext,
197  InitialLoadSet load = LoadAll);
199  USD_API
200  static UsdStageRefPtr
201  CreateNew(const std::string& identifier,
202  const ArResolverContext& pathResolverContext,
203  InitialLoadSet load = LoadAll);
204 
220  USD_API
221  static UsdStageRefPtr
224  USD_API
225  static UsdStageRefPtr
226  CreateInMemory(const std::string& identifier,
227  InitialLoadSet load = LoadAll);
229  USD_API
230  static UsdStageRefPtr
231  CreateInMemory(const std::string& identifier,
232  const ArResolverContext& pathResolverContext,
233  InitialLoadSet load = LoadAll);
235  USD_API
236  static UsdStageRefPtr
237  CreateInMemory(const std::string& identifier,
238  const SdfLayerHandle &sessionLayer,
239  InitialLoadSet load = LoadAll);
241  USD_API
242  static UsdStageRefPtr
243  CreateInMemory(const std::string& identifier,
244  const SdfLayerHandle &sessionLayer,
245  const ArResolverContext& pathResolverContext,
246  InitialLoadSet load = LoadAll);
247 
248 
263  USD_API
264  static UsdStageRefPtr
265  Open(const std::string& filePath, InitialLoadSet load = LoadAll);
267  USD_API
268  static UsdStageRefPtr
269  Open(const std::string& filePath,
270  const ArResolverContext& pathResolverContext,
271  InitialLoadSet load = LoadAll);
272 
289  USD_API
290  static UsdStageRefPtr
291  OpenMasked(const std::string &filePath,
292  UsdStagePopulationMask const &mask,
293  InitialLoadSet load = LoadAll);
295  USD_API
296  static UsdStageRefPtr
297  OpenMasked(const std::string &filePath,
298  const ArResolverContext &pathResolverContext,
299  UsdStagePopulationMask const &mask,
300  InitialLoadSet load = LoadAll);
301 
330  USD_API
331  static UsdStageRefPtr
332  Open(const SdfLayerHandle& rootLayer,
333  InitialLoadSet load=LoadAll);
335  USD_API
336  static UsdStageRefPtr
337  Open(const SdfLayerHandle& rootLayer,
338  const SdfLayerHandle& sessionLayer,
339  InitialLoadSet load=LoadAll);
341  USD_API
342  static UsdStageRefPtr
343  Open(const SdfLayerHandle& rootLayer,
344  const ArResolverContext& pathResolverContext,
345  InitialLoadSet load=LoadAll);
347  USD_API
348  static UsdStageRefPtr
349  Open(const SdfLayerHandle& rootLayer,
350  const SdfLayerHandle& sessionLayer,
351  const ArResolverContext& pathResolverContext,
352  InitialLoadSet load=LoadAll);
353 
374  USD_API
375  static UsdStageRefPtr
376  OpenMasked(const SdfLayerHandle& rootLayer,
377  const UsdStagePopulationMask &mask,
378  InitialLoadSet load=LoadAll);
380  USD_API
381  static UsdStageRefPtr
382  OpenMasked(const SdfLayerHandle& rootLayer,
383  const SdfLayerHandle& sessionLayer,
384  const UsdStagePopulationMask &mask,
385  InitialLoadSet load=LoadAll);
387  USD_API
388  static UsdStageRefPtr
389  OpenMasked(const SdfLayerHandle& rootLayer,
390  const ArResolverContext& pathResolverContext,
391  const UsdStagePopulationMask &mask,
392  InitialLoadSet load=LoadAll);
394  USD_API
395  static UsdStageRefPtr
396  OpenMasked(const SdfLayerHandle& rootLayer,
397  const SdfLayerHandle& sessionLayer,
398  const ArResolverContext& pathResolverContext,
399  const UsdStagePopulationMask &mask,
400  InitialLoadSet load=LoadAll);
401 
402  USD_API
403  virtual ~UsdStage();
404 
422  USD_API
423  void Reload();
424 
433  USD_API
434  static bool
435  IsSupportedFile(const std::string& filePath);
436 
438 
439  // --------------------------------------------------------------------- //
448 
456  USD_API
457  void Save();
458 
466  USD_API
467  void SaveSessionLayers();
468 
470 
471  // --------------------------------------------------------------------- //
517 
519  USD_API
521 
527  USD_API
528  static void
530 
532 
533  // --------------------------------------------------------------------- //
562  // --------------------------------------------------------------------- //
563 
571  USD_API
574 
580  USD_API
581  void Unload(const SdfPath& path=SdfPath::AbsoluteRootPath());
582 
594  USD_API
595  void LoadAndUnload(const SdfPathSet &loadSet, const SdfPathSet &unloadSet,
597 
608  USD_API
609  SdfPathSet GetLoadSet();
610 
630  USD_API
631  SdfPathSet FindLoadable(
632  const SdfPath& rootPath = SdfPath::AbsoluteRootPath());
633 
640  return _loadRules;
641  }
642 
652  USD_API
653  void SetLoadRules(UsdStageLoadRules const &rules);
654 
657  return _populationMask;
658  }
659 
661  USD_API
662  void SetPopulationMask(UsdStagePopulationMask const &mask);
663 
675  USD_API
677  std::function<bool (UsdRelationship const &)> const &relPred = nullptr,
678  std::function<bool (UsdAttribute const &)> const &attrPred = nullptr);
679 
681 
682  // --------------------------------------------------------------------- //
691  // --------------------------------------------------------------------- //
692 
702  USD_API
703  UsdPrim GetPseudoRoot() const;
704 
711  USD_API
712  UsdPrim GetDefaultPrim() const;
713 
721  USD_API
722  void SetDefaultPrim(const UsdPrim &prim);
723 
731  USD_API
732  void ClearDefaultPrim();
733 
741  USD_API
742  bool HasDefaultPrim() const;
743 
753  USD_API
754  UsdPrim GetPrimAtPath(const SdfPath &path) const;
755 
779  USD_API
780  UsdObject GetObjectAtPath(const SdfPath &path) const;
781 
782 private:
783  // Return the primData object at \p path.
784  Usd_PrimDataConstPtr _GetPrimDataAtPath(const SdfPath &path) const;
785  Usd_PrimDataPtr _GetPrimDataAtPath(const SdfPath &path);
786 
787  // Return the primData object at \p path. If \p path indicates a prim
788  // beneath an instance, return the primData object for the corresponding
789  // prim in the instance's master.
790  Usd_PrimDataConstPtr
791  _GetPrimDataAtPathOrInMaster(const SdfPath &path) const;
792 
793 public:
794 
811  USD_API
813 
818  USD_API
819  UsdPrimRange Traverse(const Usd_PrimFlagsPredicate &predicate);
820 
825  USD_API
827 
846  USD_API
847  UsdPrim OverridePrim(const SdfPath &path);
848 
872  USD_API
873  UsdPrim DefinePrim(const SdfPath &path,
874  const TfToken &typeName=TfToken());
875 
888  USD_API
889  UsdPrim CreateClassPrim(const SdfPath &rootPrimPath);
890 
912  USD_API
913  bool RemovePrim(const SdfPath& path);
914 
916 
917  // --------------------------------------------------------------------- //
921  // --------------------------------------------------------------------- //
922 
924  USD_API
925  SdfLayerHandle GetSessionLayer() const;
926 
928  USD_API
929  SdfLayerHandle GetRootLayer() const;
930 
935  USD_API
937 
947  USD_API
948  std::string
949  ResolveIdentifierToEditTarget(std::string const &identifier) const;
950 
957  USD_API
958  SdfLayerHandleVector GetLayerStack(bool includeSessionLayers=true) const;
959 
971  USD_API
972  SdfLayerHandleVector GetUsedLayers(bool includeClipLayers=true) const;
973 
976  USD_API
977  bool HasLocalLayer(const SdfLayerHandle &layer) const;
978 
980  USD_API
981  const UsdEditTarget &GetEditTarget() const;
982 
986  USD_API
988 
992  USD_API
993  UsdEditTarget GetEditTargetForLocalLayer(const SdfLayerHandle &layer);
994 
1001  USD_API
1002  void SetEditTarget(const UsdEditTarget &editTarget);
1003 
1032  USD_API
1033  void MuteLayer(const std::string &layerIdentifier);
1034 
1037  USD_API
1038  void UnmuteLayer(const std::string &layerIdentifier);
1039 
1047  USD_API
1048  void MuteAndUnmuteLayers(const std::vector<std::string> &muteLayers,
1049  const std::vector<std::string> &unmuteLayers);
1050 
1052  USD_API
1053  const std::vector<std::string>& GetMutedLayers() const;
1054 
1059  USD_API
1060  bool IsLayerMuted(const std::string& layerIdentifier) const;
1061 
1063 
1064  // --------------------------------------------------------------------- //
1068  // --------------------------------------------------------------------- //
1069  // Future Work:
1070  // * Flatten sub-trees or individual prims
1071  // * Allow flattening of local LayerStack
1072  // * Move Flatten into a free-function to ensure it doesn't rely on
1073  // Stage internals.
1074 
1082  USD_API
1083  bool Export(const std::string &filename,
1084  bool addSourceFileComment=true,
1085  const SdfLayer::FileFormatArguments &args =
1087 
1095  USD_API
1096  bool ExportToString(std::string *result,
1097  bool addSourceFileComment=true) const;
1098 
1125  USD_API
1126  SdfLayerRefPtr Flatten(bool addSourceFileComment=true) const;
1128 
1129 public:
1130  // --------------------------------------------------------------------- //
1138  // --------------------------------------------------------------------- //
1139 
1151  template <class T>
1152  bool GetMetadata(const TfToken &key, T *value) const;
1154  USD_API
1155  bool GetMetadata(const TfToken &key, VtValue *value) const;
1156 
1163  USD_API
1164  bool HasMetadata(const TfToken &key) const;
1165 
1174  USD_API
1175  bool HasAuthoredMetadata(const TfToken &key) const;
1176 
1185  template<typename T>
1186  bool SetMetadata(const TfToken &key, const T &value) const;
1188  USD_API
1189  bool SetMetadata(const TfToken &key, const VtValue &value) const;
1190 
1199  USD_API
1200  bool ClearMetadata(const TfToken &key) const;
1201 
1217  template<typename T>
1218  bool GetMetadataByDictKey(const TfToken& key, const TfToken &keyPath,
1219  T* value) const;
1221  USD_API
1222  bool GetMetadataByDictKey(
1223  const TfToken& key, const TfToken &keyPath, VtValue *value) const;
1224 
1235  USD_API
1236  bool HasMetadataDictKey(
1237  const TfToken& key, const TfToken &keyPath) const;
1238 
1247  USD_API
1249  const TfToken& key, const TfToken &keyPath) const;
1250 
1262  template<typename T>
1263  bool SetMetadataByDictKey(const TfToken& key, const TfToken &keyPath,
1264  const T& value) const;
1266  USD_API
1267  bool SetMetadataByDictKey(
1268  const TfToken& key, const TfToken &keyPath, const VtValue& value) const;
1269 
1281  USD_API
1283  const TfToken& key, const TfToken& keyPath) const;
1284 
1286 
1287  // --------------------------------------------------------------------- //
1294  // --------------------------------------------------------------------- //
1298  USD_API
1299  double GetStartTimeCode() const;
1300 
1307  USD_API
1308  void SetStartTimeCode(double);
1309 
1313  USD_API
1314  double GetEndTimeCode() const;
1315 
1322  USD_API
1323  void SetEndTimeCode(double);
1324 
1327  USD_API
1328  bool HasAuthoredTimeCodeRange() const;
1329 
1338  USD_API
1339  double GetTimeCodesPerSecond() const;
1340 
1349  USD_API
1350  void SetTimeCodesPerSecond(double timeCodesPerSecond) const;
1351 
1361  USD_API
1362  double GetFramesPerSecond() const;
1363 
1372  USD_API
1373  void SetFramesPerSecond(double framesPerSecond) const;
1374 
1376 
1377  // --------------------------------------------------------------------- //
1423  // --------------------------------------------------------------------- //
1424 
1430  USD_API
1431  void SetColorConfiguration(const SdfAssetPath &colorConfig) const;
1432 
1437  USD_API
1439 
1444  USD_API
1445  void SetColorManagementSystem(const TfToken &cms) const;
1446 
1451  USD_API
1453 
1465  USD_API
1466  static void GetColorConfigFallbacks(SdfAssetPath *colorConfiguration,
1467  TfToken *colorManagementSystem);
1468 
1482  USD_API
1483  static void
1484  SetColorConfigFallbacks(const SdfAssetPath &colorConfiguration,
1485  const TfToken &colorManagementSystem);
1486 
1488 
1489  // --------------------------------------------------------------------- //
1496  // --------------------------------------------------------------------- //
1497 
1502  USD_API
1503  void SetInterpolationType(UsdInterpolationType interpolationType);
1504 
1507  USD_API
1509 
1511 
1512  // --------------------------------------------------------------------- //
1517  // --------------------------------------------------------------------- //
1518 
1520  USD_API
1521  std::vector<UsdPrim> GetMasters() const;
1522 
1524 
1525 private:
1526  struct _IncludePayloadsPredicate;
1527 
1528  // --------------------------------------------------------------------- //
1529  // Stage Construction & Initialization
1530  // --------------------------------------------------------------------- //
1531 
1532  UsdStage(const SdfLayerRefPtr& rootLayer,
1533  const SdfLayerRefPtr& sessionLayer,
1534  const ArResolverContext& pathResolverContext,
1535  const UsdStagePopulationMask& mask,
1536  InitialLoadSet load);
1537 
1538  // Helper for Open() overloads -- searches and publishes to bound caches.
1539  template <class... Args>
1540  static UsdStageRefPtr _OpenImpl(InitialLoadSet load, Args const &... args);
1541 
1542  // Releases resources used by this stage.
1543  void _Close();
1544 
1545  // Common ref ptr initialization, called by public, static constructors.
1546  //
1547  // This method will either return a valid refptr (if the stage is correctly
1548  // initialized) or it will return a null ref pointer, deleting the
1549  // raw stage pointer in the process.
1550  static UsdStageRefPtr
1551  _InstantiateStage(const SdfLayerRefPtr &rootLayer,
1552  const SdfLayerRefPtr &sessionLayer,
1553  const ArResolverContext &pathResolverContext,
1554  const UsdStagePopulationMask &mask,
1555  InitialLoadSet load);
1556 
1557  // --------------------------------------------------------------------- //
1558  // Spec Existence & Definition Helpers
1559  // --------------------------------------------------------------------- //
1560 
1561  SdfPropertySpecHandleVector
1562  _GetPropertyStack(const UsdProperty &prop, UsdTimeCode time) const;
1563 
1564  SdfPropertySpecHandle
1565  _GetPropertyDefinition(const UsdPrim &prim, const TfToken &propName) const;
1566 
1567  SdfPropertySpecHandle
1568  _GetPropertyDefinition(const UsdProperty &prop) const;
1569 
1570  template <class PropType>
1572  _GetPropertyDefinition(const UsdProperty &prop) const;
1573 
1574  SdfAttributeSpecHandle
1575  _GetAttributeDefinition(const UsdAttribute &attr) const;
1576 
1577  SdfRelationshipSpecHandle
1578  _GetRelationshipDefinition(const UsdRelationship &rel) const;
1579 
1580  SdfPrimSpecHandle
1581  _CreatePrimSpecForEditing(const UsdPrim& prim);
1582 
1583  template <class PropType>
1585  _CreatePropertySpecForEditing(const UsdProperty &prop);
1586 
1587  SdfPropertySpecHandle
1588  _CreatePropertySpecForEditing(const UsdProperty &prop);
1589 
1590  SdfAttributeSpecHandle
1591  _CreateAttributeSpecForEditing(const UsdAttribute &attr);
1592 
1593  SdfRelationshipSpecHandle
1594  _CreateRelationshipSpecForEditing(const UsdRelationship &rel);
1595 
1596  // Check if the given path is valid to use with the prim creation API,
1597  // like DefinePrim. If it is valid, returns (true, GetPrimAtPath(path)).
1598  // Otherwise, returns (false, UsdPrim()).
1599  std::pair<bool, UsdPrim>
1600  _IsValidPathForCreatingPrim(const SdfPath &path) const;
1601 
1602  // Validates that editing a specified prim is allowed. If editing is not
1603  // allowed, issues a coding error like "Cannot <operation> ..." and
1604  // returns false. Otherwise, returns true.
1605  bool _ValidateEditPrim(const UsdPrim &prim, const char* operation) const;
1606  bool _ValidateEditPrimAtPath(const SdfPath &primPath,
1607  const char* operation) const;
1608 
1609  UsdPrim _DefinePrim(const SdfPath &path, const TfToken &typeName);
1610 
1611  bool _RemoveProperty(const SdfPath& path);
1612 
1613  UsdProperty _FlattenProperty(const UsdProperty &srcProp,
1614  const UsdPrim &dstParent,
1615  const TfToken &dstName);
1616 
1617  // --------------------------------------------------------------------- //
1618  // Value & Metadata Authoring
1619  // --------------------------------------------------------------------- //
1620 
1621  template <class T>
1622  bool _SetValue(
1623  UsdTimeCode time, const UsdAttribute &attr, const T &newValue);
1624  bool _SetValue(
1625  UsdTimeCode time, const UsdAttribute &attr, const VtValue &newValue);
1626 
1627  template <class T>
1628  bool _SetEditTargetMappedValue(
1629  UsdTimeCode time, const UsdAttribute &attr, const T &newValue);
1630 
1631  template <class T>
1632  bool _SetValueImpl(
1633  UsdTimeCode time, const UsdAttribute &attr, const T& value);
1634 
1635  bool _ClearValue(UsdTimeCode time, const UsdAttribute &attr);
1636 
1637  template <class T>
1638  bool _SetEditTargetMappedMetadata(
1639  const UsdObject &obj, const TfToken& fieldName,
1640  const TfToken &keyPath, const T &newValue);
1641 
1642  template <class T>
1643  bool _SetMetadataImpl(
1644  const UsdObject &obj, const TfToken& fieldName,
1645  const TfToken &keyPath, const T &value);
1646 
1647  bool _ClearMetadata(const UsdObject &obj, const TfToken& fieldName,
1648  const TfToken &keyPath=TfToken());
1649 
1650  // --------------------------------------------------------------------- //
1651  // Misc Internal Helpers
1652  // --------------------------------------------------------------------- //
1653 
1654  // Pcp helpers.
1655  PcpCache const *_GetPcpCache() const { return _cache.get(); }
1656  PcpCache *_GetPcpCache() { return _cache.get(); }
1657 
1658  // Returns the PrimIndex, using the read-only PcpCache API. We expect prims
1659  // to be composed during initial stage composition, so this method should
1660  // not be used in that context.
1661  const PcpPrimIndex* _GetPcpPrimIndex(const SdfPath& primPath) const;
1662 
1663  // Helper to report pcp errors.
1664  void _ReportPcpErrors(const PcpErrorVector &errors,
1665  const std::string &context) const;
1666  void _ReportErrors(const PcpErrorVector &errors,
1667  const std::vector<std::string>& otherErrors,
1668  const std::string &context) const;
1669 
1670  // --------------------------------------------------------------------- //
1671  // Scenegraph Composition & Change Processing
1672  // --------------------------------------------------------------------- //
1673 
1674  // Compose the prim indexes in the subtrees rooted at the paths in
1675  // \p primIndexPaths. If \p instanceChanges is given, returns
1676  // changes to masters and instances due to the discovery of new instances
1677  // during composition.
1678  void _ComposePrimIndexesInParallel(
1679  const std::vector<SdfPath>& primIndexPaths,
1680  const std::string& context,
1681  Usd_InstanceChanges* instanceChanges = nullptr);
1682 
1683  // Recompose the subtree rooted at \p prim: compose its type, flags, and
1684  // list of children, then invoke _ComposeSubtree on all its children.
1685  void _ComposeSubtree(
1686  Usd_PrimDataPtr prim, Usd_PrimDataConstPtr parent,
1687  UsdStagePopulationMask const *mask,
1688  const SdfPath &primIndexPath = SdfPath());
1689  void _ComposeSubtreeImpl(
1690  Usd_PrimDataPtr prim, Usd_PrimDataConstPtr parent,
1691  UsdStagePopulationMask const *mask,
1692  const SdfPath &primIndexPath = SdfPath());
1693  void _ComposeSubtreeInParallel(Usd_PrimDataPtr prim);
1694  void _ComposeSubtreesInParallel(
1695  const std::vector<Usd_PrimDataPtr> &prims,
1696  const std::vector<SdfPath> *primIndexPaths = nullptr);
1697 
1698  // Compose subtree rooted at \p prim under \p parent. This function
1699  // ensures that the appropriate prim index is specified for \p prim if
1700  // \p parent is in a master.
1701  void _ComposeChildSubtree(Usd_PrimDataPtr prim,
1702  Usd_PrimDataConstPtr parent,
1703  UsdStagePopulationMask const *mask);
1704 
1705  // Compose \p prim's list of children and make any modifications necessary
1706  // to its _children member and the stage's _primMap, including possibly
1707  // instantiating new prims, or destroying existing subtrees of prims. The
1708  // any newly created prims *do not* have their prim index, type, flags, or
1709  // children composed.
1710  //
1711  // Compose only \p prim's direct children if recurse=false. Otherwise
1712  // recompose every descendent of \p prim. Callers that pass recurse=false
1713  // should invoke _ComposeSubtree on any newly created prims to ensure caches
1714  // are correctly populated.
1715  void _ComposeChildren(Usd_PrimDataPtr prim,
1716  UsdStagePopulationMask const *mask, bool recurse);
1717 
1718  // Instantiate a prim instance. There must not already be an instance
1719  // at \p primPath.
1720  Usd_PrimDataPtr _InstantiatePrim(const SdfPath &primPath);
1721 
1722  // For \p prim and all of its descendants, remove from _primMap and empty
1723  // their _children vectors.
1724  void _DestroyPrim(Usd_PrimDataPtr prim);
1725 
1726  // Destroy the prim subtrees rooted at each path in \p paths. \p paths may
1727  // not contain any path that is a descendent of another path in \p paths.
1728  void _DestroyPrimsInParallel(const std::vector<SdfPath>& paths);
1729 
1730  // Invoke _DestroyPrim() on all of \p prim's direct children.
1731  void _DestroyDescendents(Usd_PrimDataPtr prim);
1732 
1733  // Returns true if the object at the given path is a descendant of
1734  // an instance prim, i.e. a prim beneath an instance prim, or a property
1735  // of a prim beneath an instance prim.
1736  bool _IsObjectDescendantOfInstance(const SdfPath& path) const;
1737 
1738  // If the given prim is an instance, returns the corresponding
1739  // master prim. Otherwise, returns an invalid prim.
1740  Usd_PrimDataConstPtr _GetMasterForInstance(Usd_PrimDataConstPtr p) const;
1741 
1742  // Returns the path of the Usd prim using the prim index at the given path.
1743  SdfPath _GetPrimPathUsingPrimIndexAtPath(const SdfPath& primIndexPath) const;
1744 
1745  // Update stage contents in response to changes in scene description.
1746  void _HandleLayersDidChange(const SdfNotice::LayersDidChangeSentPerLayer &);
1747 
1748  // Remove scene description for the prim at \p fullPath in the current edit
1749  // target.
1750  bool _RemovePrim(const SdfPath& fullPath);
1751 
1752  SdfPrimSpecHandle _GetPrimSpec(const SdfPath& fullPath);
1753 
1754  // Find and return the defining spec type for the property spec at the given
1755  // path, or SdfSpecTypeUnknown if none exists. The defining spec type is
1756  // either the builtin definition's spec type, if the indicated property is
1757  // builtin, otherwise it's the strongest authored spec's type if one exists,
1758  // otherwise it's SdfSpecTypeUnknown.
1759  SdfSpecType _GetDefiningSpecType(Usd_PrimDataConstPtr primData,
1760  const TfToken &propName) const;
1761 
1762  // Helper to apply Pcp changes and recompose the scenegraph accordingly,
1763  // given an optional initial set of paths to recompose.
1764  void _Recompose(const PcpChanges &changes);
1765  template <class T>
1766  void _Recompose(const PcpChanges &changes, T *pathsToRecompose);
1767  template <class T>
1768  void _RecomposePrims(const PcpChanges &changes, T *pathsToRecompose);
1769 
1770  // Helper for _Recompose to find the subtrees that need to be
1771  // fully recomposed and to recompose the name children of the
1772  // parents of these subtrees. Note that [start, finish) must be a
1773  // sorted range of paths with no descendent paths.
1774  template <class Iter>
1775  void _ComputeSubtreesToRecompose(Iter start, Iter finish,
1776  std::vector<Usd_PrimDataPtr>* recompose);
1777 
1778  // Helper for _Recompose to remove master subtrees in \p subtreesToRecompose
1779  // that would be composed when an instance subtree in the same container
1780  // is composed.
1781  template <class PrimIndexPathMap>
1782  void _RemoveMasterSubtreesSubsumedByInstances(
1783  std::vector<Usd_PrimDataPtr>* subtreesToRecompose,
1784  const PrimIndexPathMap& primPathToSourceIndexPathMap) const;
1785 
1786  // return true if the path is valid for load/unload operations.
1787  // This method will emit errors when invalid paths are encountered.
1788  bool _IsValidForLoad(const SdfPath& path) const;
1789  bool _IsValidForUnload(const SdfPath& path) const;
1790 
1791  // Discover all payloads in a given subtree, adding the path of each
1792  // discovered prim index to the \p primIndexPaths set. If specified,
1793  // the corresponding UsdPrim path will be added to the \p usdPrimPaths
1794  // set. The root path will be considered for inclusion in the result set.
1795  //
1796  // Note that some payloads may not be discoverable in until an ancestral
1797  // payload has been included. UsdStage::LoadAndUnload takes this into
1798  // account.
1799  void _DiscoverPayloads(const SdfPath& rootPath,
1800  UsdLoadPolicy policy,
1801  SdfPathSet* primIndexPaths,
1802  bool unloadedOnly = false,
1803  SdfPathSet* usdPrimPaths = nullptr) const;
1804 
1805  // ===================================================================== //
1806  // VALUE RESOLUTION //
1807  // ===================================================================== //
1808  // --------------------------------------------------------------------- //
1809  // Specialized Value Resolution
1810  // --------------------------------------------------------------------- //
1811 
1812  // Specifier composition is special. See comments in .cpp in
1813  // _ComposeSpecifier. This method returns either the authored specifier or
1814  // the fallback value registered in Sdf.
1815  SdfSpecifier _GetSpecifier(const UsdPrim &prim) const;
1816  SdfSpecifier _GetSpecifier(Usd_PrimDataConstPtr primData) const;
1817 
1818  // Custom is true if it is true anywhere in the stack.
1819  bool _IsCustom(const UsdProperty &prop) const;
1820 
1821  // Variability is determined by the weakest opinion in the stack.
1822  SdfVariability _GetVariability(const UsdProperty &prop) const;
1823 
1824  // Helper functions for resolving asset paths during value resolution.
1825  void _MakeResolvedAssetPaths(UsdTimeCode time, const UsdAttribute &attr,
1826  SdfAssetPath *assetPaths,
1827  size_t numAssetPaths,
1828  bool anchorAssetPathsOnly = false) const;
1829 
1830  void _MakeResolvedAssetPathsValue(UsdTimeCode time, const UsdAttribute &attr,
1831  VtValue *value,
1832  bool anchorAssetPathsOnly = false) const;
1833 
1834  void _MakeResolvedTimeCodes(UsdTimeCode time, const UsdAttribute &attr,
1835  SdfTimeCode *timeCodes,
1836  size_t numTimeCodes) const;
1837 
1838  void _MakeResolvedAttributeValue(UsdTimeCode time, const UsdAttribute &attr,
1839  VtValue *value) const;
1840 
1841  // --------------------------------------------------------------------- //
1842  // Metadata Resolution
1843  // --------------------------------------------------------------------- //
1844  bool _GetMetadata(const UsdObject &obj,
1845  const TfToken& fieldName,
1846  const TfToken &keyPath,
1847  bool useFallbacks,
1848  VtValue* result) const;
1849 
1850  bool _GetMetadata(const UsdObject &obj,
1851  const TfToken& fieldName,
1852  const TfToken &keyPath,
1853  bool useFallbacks,
1854  SdfAbstractDataValue* result) const;
1855 
1856  template <class T>
1857  bool _GetMetadataImpl(const UsdObject &obj, const TfToken& fieldName,
1858  T* value) const;
1859 
1860  template <class Composer>
1861  void _GetAttrTypeImpl(const UsdAttribute &attr,
1862  const TfToken &fieldName,
1863  bool useFallbacks,
1864  Composer *composer) const;
1865 
1866  template <class Composer>
1867  void _GetAttrVariabilityImpl(const UsdAttribute &attr,
1868  bool useFallbacks,
1869  Composer *composer) const;
1870 
1871  template <class Composer>
1872  void _GetPropCustomImpl(const UsdProperty &prop,
1873  bool useFallbacks,
1874  Composer *composer) const;
1875 
1876  template <class Composer>
1877  void _GetPrimTypeNameImpl(const UsdPrim &prim,
1878  bool useFallbacks,
1879  Composer *composer) const;
1880 
1881  template <class Composer>
1882  bool _GetPrimSpecifierImpl(Usd_PrimDataConstPtr primData,
1883  bool useFallbacks, Composer *composer) const;
1884 
1885  template <class ListOpType, class Composer>
1886  bool _GetListOpMetadataImpl(const UsdObject &obj,
1887  const TfToken &fieldName,
1888  bool useFallbacks,
1889  Usd_Resolver *resolver,
1890  Composer *composer) const;
1891 
1892  template <class Composer>
1893  bool _GetSpecialMetadataImpl(const UsdObject &obj,
1894  const TfToken &fieldName,
1895  const TfToken &keyPath,
1896  bool useFallbacks,
1897  Composer *composer) const;
1898  template <class Composer>
1899  bool _GetMetadataImpl(const UsdObject &obj,
1900  const TfToken& fieldName,
1901  const TfToken& keyPath,
1902  bool includeFallbacks,
1903  Composer *composer) const;
1904 
1905  template <class Composer>
1906  bool _GetGeneralMetadataImpl(const UsdObject &obj,
1907  const TfToken& fieldName,
1908  const TfToken& keyPath,
1909  bool includeFallbacks,
1910  Composer *composer) const;
1911 
1912  template <class Composer>
1913  bool _ComposeGeneralMetadataImpl(const UsdObject &obj,
1914  const TfToken& fieldName,
1915  const TfToken& keyPath,
1916  bool includeFallbacks,
1917  Usd_Resolver* resolver,
1918  Composer *composer) const;
1919 
1920  // NOTE: The "authoredOnly" flag is not yet in use, but when we have
1921  // support for prim-based metadata fallbacks, they should be ignored when
1922  // this flag is set to true.
1923  bool _HasMetadata(const UsdObject &obj, const TfToken& fieldName,
1924  const TfToken &keyPath, bool useFallbacks) const;
1925 
1927  _ListMetadataFields(const UsdObject &obj, bool useFallbacks) const;
1928 
1929  void _GetAllMetadata(const UsdObject &obj,
1930  bool useFallbacks,
1931  UsdMetadataValueMap* result,
1932  bool anchorAssetPathsOnly = false) const;
1933 
1934  template <class Composer>
1935  bool
1936  _GetFallbackMetadataImpl(const UsdObject &obj,
1937  const TfToken &fieldName,
1938  const TfToken &keyPath,
1939  Composer *composer) const;
1940 
1941  // --------------------------------------------------------------------- //
1942  // Default & TimeSample Resolution
1943  // --------------------------------------------------------------------- //
1944 
1945  void _GetResolveInfo(const UsdAttribute &attr,
1946  UsdResolveInfo *resolveInfo,
1947  const UsdTimeCode *time = nullptr) const;
1948 
1949  template <class T> struct _ExtraResolveInfo;
1950 
1951  template <class T>
1952  void _GetResolveInfo(const UsdAttribute &attr,
1953  UsdResolveInfo *resolveInfo,
1954  const UsdTimeCode *time = nullptr,
1955  _ExtraResolveInfo<T> *extraInfo = nullptr) const;
1956 
1957  template <class T> struct _ResolveInfoResolver;
1958  struct _PropertyStackResolver;
1959 
1960  template <class Resolver>
1961  void _GetResolvedValueImpl(const UsdProperty &prop,
1962  Resolver *resolver,
1963  const UsdTimeCode *time = nullptr) const;
1964 
1965  bool _GetValue(UsdTimeCode time, const UsdAttribute &attr,
1966  VtValue* result) const;
1967 
1968  template <class T>
1969  bool _GetValue(UsdTimeCode time, const UsdAttribute &attr,
1970  T* result) const;
1971 
1972  template <class T>
1973  bool _GetValueImpl(UsdTimeCode time, const UsdAttribute &attr,
1974  Usd_InterpolatorBase* interpolator,
1975  T* value) const;
1976 
1978  _GetLayerWithStrongestValue(
1979  UsdTimeCode time, const UsdAttribute &attr) const;
1980 
1981 
1982 
1983  USD_API
1984  bool _GetValueFromResolveInfo(const UsdResolveInfo &info,
1985  UsdTimeCode time, const UsdAttribute &attr,
1986  VtValue* result) const;
1987 
1988  template <class T>
1989  USD_API
1990  bool _GetValueFromResolveInfo(const UsdResolveInfo &info,
1991  UsdTimeCode time, const UsdAttribute &attr,
1992  T* result) const;
1993 
1994  template <class T>
1995  bool _GetValueFromResolveInfoImpl(const UsdResolveInfo &info,
1996  UsdTimeCode time, const UsdAttribute &attr,
1997  Usd_InterpolatorBase* interpolator,
1998  T* value) const;
1999 
2000  // --------------------------------------------------------------------- //
2001  // Specialized Time Sample I/O
2002  // --------------------------------------------------------------------- //
2003 
2010  bool _GetTimeSamplesInInterval(const UsdAttribute &attr,
2011  const GfInterval& interval,
2012  std::vector<double>* times) const;
2013 
2014  bool _GetTimeSamplesInIntervalFromResolveInfo(
2015  const UsdResolveInfo &info,
2016  const UsdAttribute &attr,
2017  const GfInterval& interval,
2018  std::vector<double>* times) const;
2019 
2020  size_t _GetNumTimeSamples(const UsdAttribute &attr) const;
2021 
2022  size_t _GetNumTimeSamplesFromResolveInfo(const UsdResolveInfo &info,
2023  const UsdAttribute &attr) const;
2024 
2028  bool _GetBracketingTimeSamples(const UsdAttribute &attr,
2029  double desiredTime,
2030  bool authoredOnly,
2031  double* lower,
2032  double* upper,
2033  bool* hasSamples) const;
2034 
2035  bool _GetBracketingTimeSamplesFromResolveInfo(const UsdResolveInfo &info,
2036  const UsdAttribute &attr,
2037  double desiredTime,
2038  bool authoredOnly,
2039  double* lower,
2040  double* upper,
2041  bool* hasSamples) const;
2042 
2043  bool _ValueMightBeTimeVarying(const UsdAttribute &attr) const;
2044 
2045  bool _ValueMightBeTimeVaryingFromResolveInfo(const UsdResolveInfo &info,
2046  const UsdAttribute &attr) const;
2047 
2048  void _RegisterPerLayerNotices();
2049 
2050 private:
2051 
2052  // The 'pseudo root' prim.
2053  Usd_PrimDataPtr _pseudoRoot;
2054 
2055  // The stage's root layer.
2056  SdfLayerRefPtr _rootLayer;
2057 
2058  // Every UsdStage has an implicit, in-memory session layer.
2059  // This is to allow for runtime overrides such as variant selections.
2060  SdfLayerRefPtr _sessionLayer;
2061 
2062  // The stage's EditTarget.
2063  UsdEditTarget _editTarget;
2064 
2065  std::unique_ptr<PcpCache> _cache;
2066  std::unique_ptr<Usd_ClipCache> _clipCache;
2067  std::unique_ptr<Usd_InstanceCache> _instanceCache;
2068 
2069  // A map from Path to Prim, for fast random access.
2070  typedef TfHashMap<
2071  SdfPath, Usd_PrimDataIPtr, SdfPath::Hash> PathToNodeMap;
2072  PathToNodeMap _primMap;
2073  mutable boost::optional<tbb::spin_rw_mutex> _primMapMutex;
2074 
2075  // The interpolation type used for all attributes on the stage.
2076  UsdInterpolationType _interpolationType;
2077 
2078  typedef std::vector<
2079  std::pair<SdfLayerHandle, TfNotice::Key> > _LayerAndNoticeKeyVec;
2080  _LayerAndNoticeKeyVec _layersAndNoticeKeys;
2081  size_t _lastChangeSerialNumber;
2082 
2083  boost::optional<WorkArenaDispatcher> _dispatcher;
2084 
2085  // To provide useful aggregation of malloc stats, we bill everything
2086  // for this stage - from all access points - to this tag.
2087  char const *_mallocTagID;
2088 
2089  // The state used when instantiating the stage.
2090  const InitialLoadSet _initialLoadSet;
2091 
2092  // The population mask that applies to this stage.
2093  UsdStagePopulationMask _populationMask;
2094 
2095  // The load rules that apply to this stage.
2096  UsdStageLoadRules _loadRules;
2097 
2098  bool _isClosingStage;
2099 
2100  friend class UsdAPISchemaBase;
2101  friend class UsdAttribute;
2102  friend class UsdAttributeQuery;
2103  friend class UsdEditTarget;
2104  friend class UsdInherits;
2105  friend class UsdObject;
2106  friend class UsdPrim;
2107  friend class UsdProperty;
2108  friend class UsdRelationship;
2109  friend class UsdSpecializes;
2110  friend class UsdVariantSet;
2111  friend class UsdVariantSets;
2112  friend class Usd_FlattenAccess;
2113  friend class Usd_PcpCacheAccess;
2114  friend class Usd_PrimData;
2115  friend class Usd_StageOpenRequest;
2116  template <class T> friend struct Usd_AttrGetValueHelper;
2117  friend struct Usd_AttrGetUntypedValueHelper;
2118  template <class RefsOrPayloadsEditorType, class RefsOrPayloadsProxyType>
2119  friend struct Usd_ListEditImpl;
2120 };
2121 
2122 template<typename T>
2123 bool
2124 UsdStage::GetMetadata(const TfToken& key, T* value) const
2125 {
2126  VtValue result;
2127  if (!GetMetadata(key, &result)){
2128  return false;
2129  }
2130 
2131  if (result.IsHolding<T>()){
2132  *value = result.UncheckedGet<T>();
2133  return true;
2134  } else {
2135  TF_CODING_ERROR("Requested type %s for stage metadatum %s does not"
2136  " match retrieved type %s",
2137  ArchGetDemangled<T>().c_str(),
2138  key.GetText(),
2139  result.GetTypeName().c_str());
2140  return false;
2141  }
2142 }
2143 
2144 template<typename T>
2145 bool
2146 UsdStage::SetMetadata(const TfToken& key, const T& value) const
2147 {
2148  VtValue in(value);
2149  return SetMetadata(key, in);
2150 }
2151 
2152 template<typename T>
2153 bool
2154 UsdStage::GetMetadataByDictKey(const TfToken& key, const TfToken &keyPath,
2155  T* value) const
2156 {
2157  VtValue result;
2158  if (!GetMetadataByDictKey(key, keyPath, &result)){
2159  return false;
2160  }
2161 
2162  if (result.IsHolding<T>()){
2163  *value = result.UncheckedGet<T>();
2164  return true;
2165  } else {
2166  TF_CODING_ERROR("Requested type %s for stage metadatum %s[%s] does not"
2167  " match retrieved type %s",
2168  ArchGetDemangled<T>().c_str(),
2169  key.GetText(),
2170  keyPath.GetText(),
2171  result.GetTypeName().c_str());
2172  return false;
2173  }
2174 }
2175 
2176 template<typename T>
2177 bool
2178 UsdStage::SetMetadataByDictKey(const TfToken& key, const TfToken &keyPath,
2179  const T& value) const
2180 {
2181  VtValue in(value);
2182  return SetMetadataByDictKey(key, keyPath, in);
2183 }
2184 
2185 
2186 
2187 PXR_NAMESPACE_CLOSE_SCOPE
2188 
2189 #endif //USD_STAGE_H
2190 
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
A unit of scene description that you combine with other units of scene description to form a shot...
Definition: layer.h:93
Load no loadable prims.
Definition: stage.h:158
USD_API void SetStartTimeCode(double)
Sets the stage&#39;s start timeCode.
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 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:77
T const & UncheckedGet() const
Returns a const reference to the held object if the held object is of type T.
Definition: value.h:836
USD_API void SetLoadRules(UsdStageLoadRules const &rules)
Set the UsdStageLoadRules to govern payload inclusion on this stage.
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:171
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:87
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:91
bool IsHolding() const
Return true if this value is holding an object of type T, false otherwise.
Definition: value.h:808
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:142
UsdStageLoadRules const & GetLoadRules() const
Return the stage&#39;s current UsdStageLoadRules governing payload inclusion.
Definition: stage.h:639
USD_API void SetTimeCodesPerSecond(double timeCodesPerSecond) const
Sets the stage&#39;s timeCodesPerSecond value.
Load a prim plus all its descendants.
Definition: common.h:140
SdfSpecType
An enum that specifies the type of an object.
Definition: types.h:91
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:69
Scenegraph object for authoring and retrieving numeric, string, and array valued data, sampled over time.
Definition: attribute.h:176
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. ...
Enable a concrete base class for use with TfRefPtr.
Definition: refBase.h:72
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:656
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:89
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. ...
SdfSpecifier
An enum that identifies the possible specifiers for an SdfPrimSpec.
Definition: types.h:123
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:129
Defines a mapping from scene graph paths to Sdf spec paths in a SdfLayer where edits should be direct...
Definition: editTarget.h:78
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.
SdfVariability
An enum that identifies variability types for attributes.
Definition: types.h:182
UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a &quot;Prim&quot; as ...
Definition: prim.h:131
InitialLoadSet
Specifies the initial set of prims to load when opening a UsdStage.
Definition: stage.h:155
std::map< std::string, std::string > FileFormatArguments
Type for specifying additional file format-specific arguments to layer API.
Definition: layer.h:119
USD_API SdfPathSet GetLoadSet()
Returns a set of all loaded paths.
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:438
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:2124
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:287
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...
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.
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:138
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:2154
Contains an asset path and an optional resolved path.
Definition: assetPath.h:43
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:92
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
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:2178
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 std::vector< UsdPrim > GetMasters() const
Returns all master prims.
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.
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:211
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...
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:142
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:182
This class represents a mask that may be applied to a UsdStage to limit the set of UsdPrim s it popul...
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:157
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:2146
char const * GetText() const
Return the text that this token represents.
Definition: token.h:198