stage.h

Go to the documentation of this file.

//
// Copyright 2016 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_USD_USD_STAGE_H
#define PXR_USD_USD_STAGE_H
 
 
#include "pxr/pxr.h"
#include "pxr/usd/usd/api.h"
#include "pxr/usd/usd/common.h"
#include "pxr/usd/usd/editTarget.h"
#include "pxr/usd/usd/interpolation.h"
#include "pxr/usd/usd/schemaRegistry.h"
#include "pxr/usd/usd/stageLoadRules.h"
#include "pxr/usd/usd/stagePopulationMask.h"
#include "pxr/usd/usd/primDefinition.h"
#include "pxr/usd/usd/primFlags.h"
 
#include "pxr/base/tf/declarePtrs.h"
#include "pxr/base/tf/hashmap.h"
#include "pxr/base/tf/type.h"
#include "pxr/base/tf/weakBase.h"
 
#include "pxr/usd/ar/ar.h"
#include "pxr/usd/ar/notice.h"
#include "pxr/usd/sdf/declareHandles.h"
#include "pxr/usd/sdf/notice.h"
#include "pxr/usd/sdf/path.h"
#include "pxr/usd/sdf/types.h"
#include "pxr/usd/sdf/valueTypeName.h"
#include "pxr/usd/pcp/cache.h"
#include "pxr/base/vt/value.h"
#include "pxr/base/work/dispatcher.h"
 
#include <tbb/concurrent_vector.h>
#include <tbb/concurrent_unordered_set.h>
#include <tbb/concurrent_hash_map.h>
#include <tbb/spin_rw_mutex.h>
 
#include <functional>
#include <string>
#include <memory>
#include <optional>
#include <unordered_map>
#include <utility>
 
PXR_NAMESPACE_OPEN_SCOPE
 
class ArResolverContext;
class GfInterval;
class SdfAbstractDataValue;
class TsSpline;
class Usd_AssetPathContext;
class Usd_ClipCache;
class Usd_InstanceCache;
class Usd_InstanceChanges;
class Usd_InterpolatorBase;
class Usd_Resolver;
class UsdResolveInfo;
class UsdResolveTarget;
class UsdPrim;
class UsdPrimRange;
 
SDF_DECLARE_HANDLES(SdfLayer);
 
class UsdStage : public TfRefBase, public TfWeakBase {
public:
 
    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //
    
    enum InitialLoadSet
    {
        LoadAll, 
        LoadNone 
    };
 
    //
    USD_API
    static UsdStageRefPtr
    CreateNew(const std::string& identifier, 
              InitialLoadSet load = LoadAll);
    USD_API
    static UsdStageRefPtr
    CreateNew(const std::string& identifier,
              const SdfLayerHandle& sessionLayer,
              InitialLoadSet load = LoadAll);
    USD_API
    static UsdStageRefPtr
    CreateNew(const std::string& identifier,
              const SdfLayerHandle& sessionLayer,
              const ArResolverContext& pathResolverContext,
              InitialLoadSet load = LoadAll);
    USD_API
    static UsdStageRefPtr
    CreateNew(const std::string& identifier,
              const ArResolverContext& pathResolverContext,
              InitialLoadSet load = LoadAll);
 
    USD_API
    static UsdStageRefPtr
    CreateInMemory(InitialLoadSet load = LoadAll);
    USD_API
    static UsdStageRefPtr
    CreateInMemory(const std::string& identifier,
                   InitialLoadSet load = LoadAll);
    USD_API
    static UsdStageRefPtr
    CreateInMemory(const std::string& identifier,
                   const ArResolverContext& pathResolverContext,
                   InitialLoadSet load = LoadAll);
    USD_API
    static UsdStageRefPtr
    CreateInMemory(const std::string& identifier,
                   const SdfLayerHandle &sessionLayer,
                   InitialLoadSet load = LoadAll);
    USD_API
    static UsdStageRefPtr
    CreateInMemory(const std::string& identifier,
                   const SdfLayerHandle &sessionLayer,
                   const ArResolverContext& pathResolverContext,
                   InitialLoadSet load = LoadAll);
 
    USD_API
    static UsdStageRefPtr
    Open(const std::string& filePath, InitialLoadSet load = LoadAll);
    USD_API
    static UsdStageRefPtr
    Open(const std::string& filePath,
         const ArResolverContext& pathResolverContext,
         InitialLoadSet load = LoadAll);
 
    USD_API
    static UsdStageRefPtr
    OpenMasked(const std::string &filePath,
               UsdStagePopulationMask const &mask,
               InitialLoadSet load = LoadAll);
    USD_API
    static UsdStageRefPtr
    OpenMasked(const std::string &filePath,
               const ArResolverContext &pathResolverContext,
               UsdStagePopulationMask const &mask,
               InitialLoadSet load = LoadAll);
 
    USD_API
    static UsdStageRefPtr
    Open(const SdfLayerHandle& rootLayer,
         InitialLoadSet load=LoadAll);
    USD_API
    static UsdStageRefPtr
    Open(const SdfLayerHandle& rootLayer,
         const SdfLayerHandle& sessionLayer,
         InitialLoadSet load=LoadAll);
    USD_API
    static UsdStageRefPtr
    Open(const SdfLayerHandle& rootLayer,
         const ArResolverContext& pathResolverContext,
         InitialLoadSet load=LoadAll);
    USD_API
    static UsdStageRefPtr
    Open(const SdfLayerHandle& rootLayer,
         const SdfLayerHandle& sessionLayer,
         const ArResolverContext& pathResolverContext,
         InitialLoadSet load=LoadAll);
 
    USD_API
    static UsdStageRefPtr
    OpenMasked(const SdfLayerHandle& rootLayer,
               const UsdStagePopulationMask &mask,
               InitialLoadSet load=LoadAll);
    USD_API
    static UsdStageRefPtr
    OpenMasked(const SdfLayerHandle& rootLayer,
               const SdfLayerHandle& sessionLayer,
               const UsdStagePopulationMask &mask,
               InitialLoadSet load=LoadAll);
    USD_API
    static UsdStageRefPtr
    OpenMasked(const SdfLayerHandle& rootLayer,
               const ArResolverContext& pathResolverContext,
               const UsdStagePopulationMask &mask,
               InitialLoadSet load=LoadAll);
    USD_API
    static UsdStageRefPtr
    OpenMasked(const SdfLayerHandle& rootLayer,
               const SdfLayerHandle& sessionLayer,
               const ArResolverContext& pathResolverContext,
               const UsdStagePopulationMask &mask,
               InitialLoadSet load=LoadAll);
    
    USD_API
    virtual ~UsdStage();
 
    USD_API
    void Reload();
 
    USD_API
    static bool
    IsSupportedFile(const std::string& filePath);
 
 
    // --------------------------------------------------------------------- //
 
    USD_API
    void Save();
 
    USD_API
    void SaveSessionLayers();
 
 
    // --------------------------------------------------------------------- //
 
    USD_API
    static PcpVariantFallbackMap GetGlobalVariantFallbacks();
 
    USD_API
    static void
    SetGlobalVariantFallbacks(const PcpVariantFallbackMap &fallbacks);
 
 
    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //
 
    USD_API
    UsdPrim Load(const SdfPath& path=SdfPath::AbsoluteRootPath(),
                 UsdLoadPolicy policy=UsdLoadWithDescendants);
 
    USD_API
    void Unload(const SdfPath& path=SdfPath::AbsoluteRootPath());
 
    USD_API
    void LoadAndUnload(const SdfPathSet &loadSet, const SdfPathSet &unloadSet,
                       UsdLoadPolicy policy=UsdLoadWithDescendants);
 
    USD_API
    SdfPathSet GetLoadSet();
 
    USD_API
    SdfPathSet FindLoadable(
        const SdfPath& rootPath = SdfPath::AbsoluteRootPath());
 
    UsdStageLoadRules const &GetLoadRules() const {
        return _loadRules;
    }
 
    USD_API
    void SetLoadRules(UsdStageLoadRules const &rules);
 
    UsdStagePopulationMask GetPopulationMask() const {
        return _populationMask;
    }
 
    USD_API
    void SetPopulationMask(UsdStagePopulationMask const &mask);
 
    USD_API
    void ExpandPopulationMask(
        Usd_PrimFlagsPredicate const &traversalPredicate,
        std::function<bool (UsdRelationship const &)> const &relPred = nullptr,
        std::function<bool (UsdAttribute const &)> const &attrPred = nullptr);
 
    USD_API
    void ExpandPopulationMask(
        std::function<bool (UsdRelationship const &)> const &relPred = nullptr,
        std::function<bool (UsdAttribute const &)> const &attrPred = nullptr);
 
 
    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //
 
    USD_API
    UsdPrim GetPseudoRoot() const;
 
    USD_API
    UsdPrim GetDefaultPrim() const;
 
    USD_API
    void SetDefaultPrim(const UsdPrim &prim);
    
    USD_API
    void ClearDefaultPrim();
 
    USD_API
    bool HasDefaultPrim() const;
 
    USD_API
    UsdPrim GetPrimAtPath(const SdfPath &path) const;
 
    USD_API
    UsdObject GetObjectAtPath(const SdfPath &path) const;
 
    USD_API
    UsdProperty GetPropertyAtPath(const SdfPath &path) const;
 
    USD_API
    UsdAttribute GetAttributeAtPath(const SdfPath &path) const;
 
    USD_API
    UsdRelationship GetRelationshipAtPath(const SdfPath &path) const;
private:
    // Return the primData object at \p path.
    Usd_PrimDataConstPtr _GetPrimDataAtPath(const SdfPath &path) const;
    Usd_PrimDataPtr _GetPrimDataAtPath(const SdfPath &path);
 
    // Return the primData object at \p path.  If \p path indicates a prim
    // beneath an instance, return the primData object for the corresponding 
    // prim in the instance's prototype.
    Usd_PrimDataConstPtr 
    _GetPrimDataAtPathOrInPrototype(const SdfPath &path) const;
 
    std::vector<UsdPrim>
    _GetInstancesForPrototype(const UsdPrim& prototype) const;
 
public:
 
    USD_API
    UsdPrimRange Traverse();
 
    USD_API
    UsdPrimRange Traverse(const Usd_PrimFlagsPredicate &predicate);
 
    USD_API
    UsdPrimRange TraverseAll();
 
    USD_API
    UsdPrim OverridePrim(const SdfPath &path);
 
    USD_API
    UsdPrim DefinePrim(const SdfPath &path,
                       const TfToken &typeName=TfToken());
 
    USD_API
    UsdPrim CreateClassPrim(const SdfPath &rootPrimPath);
 
    USD_API
    bool RemovePrim(const SdfPath& path);
 
 
    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //
 
    USD_API
    SdfLayerHandle GetSessionLayer() const;
 
    USD_API
    SdfLayerHandle GetRootLayer() const;
 
    USD_API
    ArResolverContext GetPathResolverContext() const;
 
    USD_API
    std::string
    ResolveIdentifierToEditTarget(std::string const &identifier) const;
 
    USD_API
    PcpErrorVector GetCompositionErrors() const;
 
    USD_API
    SdfLayerHandleVector GetLayerStack(bool includeSessionLayers=true) const;
 
    USD_API
    SdfLayerHandleVector GetUsedLayers(bool includeClipLayers=true) const;
 
    USD_API
    bool HasLocalLayer(const SdfLayerHandle &layer) const;
    
    USD_API
    const UsdEditTarget &GetEditTarget() const;
 
    USD_API
    UsdEditTarget GetEditTargetForLocalLayer(size_t i);
 
    USD_API
    UsdEditTarget GetEditTargetForLocalLayer(const SdfLayerHandle &layer);
 
    USD_API
    void SetEditTarget(const UsdEditTarget &editTarget);
 
    USD_API
    void MuteLayer(const std::string &layerIdentifier);
 
    USD_API
    void UnmuteLayer(const std::string &layerIdentifier);
 
    USD_API
    void MuteAndUnmuteLayers(const std::vector<std::string> &muteLayers,
                             const std::vector<std::string> &unmuteLayers);
 
    USD_API
    const std::vector<std::string>& GetMutedLayers() const;
 
    USD_API
    bool IsLayerMuted(const std::string& layerIdentifier) const;
 
 
    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //
    // Future Work:
    //    * Flatten sub-trees or individual prims
    //    * Allow flattening of local LayerStack
    //    * Move Flatten into a free-function to ensure it doesn't rely on
    //      Stage internals.
 
    USD_API
    bool Export(const std::string &filename,
                bool addSourceFileComment=true,
                const SdfLayer::FileFormatArguments &args = 
                    SdfLayer::FileFormatArguments()) const;
 
    USD_API
    bool ExportToString(std::string *result,
                        bool addSourceFileComment=true) const;
 
    USD_API
    SdfLayerRefPtr Flatten(bool addSourceFileComment=true) const;
 
public:
    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //
 
    template <class T>
    bool GetMetadata(const TfToken &key, T *value) const;
    USD_API
    bool GetMetadata(const TfToken &key, VtValue *value) const;
 
    USD_API
    bool HasMetadata(const TfToken &key) const;
 
    USD_API
    bool HasAuthoredMetadata(const TfToken &key) const;
 
    USD_API
    bool SetMetadata(const TfToken &key, VtValueRef value) const;
 
    USD_API
    bool ClearMetadata(const TfToken &key) const;
 
    template<typename T>
    bool GetMetadataByDictKey(const TfToken& key, const TfToken &keyPath, 
                              T* value) const;
    USD_API
    bool GetMetadataByDictKey(
        const TfToken& key, const TfToken &keyPath, VtValue *value) const;
 
    USD_API
    bool HasMetadataDictKey(
        const TfToken& key, const TfToken &keyPath) const;
 
    USD_API
    bool HasAuthoredMetadataDictKey(
        const TfToken& key, const TfToken &keyPath) const;
 
    USD_API
    bool SetMetadataByDictKey(
        const TfToken& key, const TfToken &keyPath, VtValueRef value) const;
 
    USD_API
    bool ClearMetadataByDictKey(
        const TfToken& key, const TfToken& keyPath) const;
 
    USD_API
    void WriteFallbackPrimTypes();
 
 
    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //
    USD_API
    double GetStartTimeCode() const;
 
    USD_API
    void SetStartTimeCode(double);
 
    USD_API
    double GetEndTimeCode() const;
 
    USD_API
    void SetEndTimeCode(double);
 
    USD_API
    bool HasAuthoredTimeCodeRange() const;
 
    USD_API
    double GetTimeCodesPerSecond() const;
 
    USD_API
    void SetTimeCodesPerSecond(double timeCodesPerSecond) const;
 
    USD_API
    double GetFramesPerSecond() const;
    
    USD_API
    void SetFramesPerSecond(double framesPerSecond) const;
    
 
    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //
 
    USD_API
    void SetColorConfiguration(const SdfAssetPath &colorConfig) const;
 
    USD_API
    SdfAssetPath GetColorConfiguration() const;
 
    USD_API
    void SetColorManagementSystem(const TfToken &cms) const;
 
    USD_API
    TfToken GetColorManagementSystem() const;
 
    USD_API
    static void GetColorConfigFallbacks(SdfAssetPath *colorConfiguration,
                                        TfToken *colorManagementSystem);
 
    USD_API
    static void
    SetColorConfigFallbacks(const SdfAssetPath &colorConfiguration, 
                            const TfToken &colorManagementSystem);
 
 
    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //
 
    USD_API
    void SetInterpolationType(UsdInterpolationType interpolationType);
 
    USD_API
    UsdInterpolationType GetInterpolationType() const;
 
 
    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //
 
    USD_API
    std::vector<UsdPrim> GetPrototypes() const;
 
 
private:
    struct _IncludePayloadsPredicate;
 
    // --------------------------------------------------------------------- //
    // Stage Construction & Initialization
    // --------------------------------------------------------------------- //
 
    UsdStage(const SdfLayerRefPtr& rootLayer,
             const SdfLayerRefPtr& sessionLayer,
             const ArResolverContext& pathResolverContext,
             const UsdStagePopulationMask& mask,
             InitialLoadSet load);
 
    // Helper for Open() overloads -- searches and publishes to bound caches.
    template <class... Args>
    static UsdStageRefPtr _OpenImpl(InitialLoadSet load, Args const &... args);
 
    // Releases resources used by this stage.
    void _Close();
 
    // Common ref ptr initialization, called by public, static constructors.
    //
    // This method will either return a valid refptr (if the stage is correctly
    // initialized) or it will return a null ref pointer, deleting the
    // raw stage pointer in the process.
    static UsdStageRefPtr
    _InstantiateStage(const SdfLayerRefPtr &rootLayer,
                      const SdfLayerRefPtr &sessionLayer,
                      const ArResolverContext &pathResolverContext,
                      const UsdStagePopulationMask &mask,
                      InitialLoadSet load);
 
    // --------------------------------------------------------------------- //
    // Spec Existence & Definition Helpers
    // --------------------------------------------------------------------- //
 
    SdfPropertySpecHandleVector
    _GetPropertyStack(const UsdProperty &prop, UsdTimeCode time) const;
 
    std::vector<std::pair<SdfPropertySpecHandle, SdfLayerOffset>> 
    _GetPropertyStackWithLayerOffsets(
        const UsdProperty &prop, UsdTimeCode time) const;
 
    static SdfPrimSpecHandleVector 
    _GetPrimStack(const UsdPrim &prim);
 
    static std::vector<std::pair<SdfPrimSpecHandle, SdfLayerOffset>> 
    _GetPrimStackWithLayerOffsets(const UsdPrim &prim);
 
    UsdPrimDefinition::Property
    _GetSchemaProperty(const UsdProperty &prop) const;
 
    USD_API
    UsdPrimDefinition::Attribute
    _GetSchemaAttribute(const UsdAttribute &attr) const;
 
    UsdPrimDefinition::Relationship
    _GetSchemaRelationship(const UsdRelationship &rel) const;
 
    SdfAttributeSpecHandle
    _CreateNewSpecFromSchemaAttribute(
        const UsdPrim &prim,
        const UsdPrimDefinition::Attribute &attrDef);
 
    SdfRelationshipSpecHandle
    _CreateNewSpecFromSchemaRelationship(
        const UsdPrim &prim,
        const UsdPrimDefinition::Relationship &relDef);
 
    template <class PropType> 
    SdfHandle<PropType>
    _CreateNewPropertySpecFromSchema(const UsdProperty &prop);
 
    SdfPrimSpecHandle
    _CreatePrimSpecForEditing(const UsdPrim& prim);
 
    template <class PropType>
    SdfHandle<PropType>
    _CreatePropertySpecForEditing(const UsdProperty &prop);
 
    SdfPropertySpecHandle
    _CreatePropertySpecForEditing(const UsdProperty &prop);
 
    SdfAttributeSpecHandle
    _CreateAttributeSpecForEditing(const UsdAttribute &attr);
 
    SdfRelationshipSpecHandle
    _CreateRelationshipSpecForEditing(const UsdRelationship &rel);
 
    // Check if the given path is valid to use with the prim creation API,
    // like DefinePrim. If it is valid, returns (true, GetPrimAtPath(path)).
    // Otherwise, returns (false, UsdPrim()).
    std::pair<bool, UsdPrim> 
    _IsValidPathForCreatingPrim(const SdfPath &path) const;
 
    // Validates that editing a specified prim is allowed. If editing is not
    // allowed, issues a coding error like "Cannot <operation> ..." and 
    // returns false. Otherwise, returns true.
    bool _ValidateEditPrim(const UsdPrim &prim, const char* operation) const;
    bool _ValidateEditPrimAtPath(const SdfPath &primPath, 
                                 const char* operation) const;
 
    UsdPrim _DefinePrim(const SdfPath &path, const TfToken &typeName);
 
    bool _RemoveProperty(const SdfPath& path);
 
    UsdProperty _FlattenProperty(const UsdProperty &srcProp,
                                 const UsdPrim &dstParent, 
                                 const TfToken &dstName);
 
    // --------------------------------------------------------------------- //
    // Value & Metadata Authoring
    // --------------------------------------------------------------------- //
 
    // Set value for dynamically typed VtValueRef. Will map the value across
    // edit targets if the held value type supports it.
    bool _SetValue(
        UsdTimeCode time, const UsdAttribute &attr, VtValueRef newValue);
 
    TfToken _GetAttributeValueTypeNameToken(const UsdAttribute &attr) const;
    SdfValueTypeName _GetAttributeValueTypeName(const UsdAttribute &attr) const;
    TfType _GetAttributeValueType(const UsdAttribute &attr) const;
 
    bool _ClearValue(UsdTimeCode time, const UsdAttribute &attr);
 
    // Set metadata for dynamically typed VtValueRef. Will map the value across 
    // edit targets if the value type supports it.
    USD_API
    bool _SetMetadata(const UsdObject &object,
                      const TfToken& key,
                      const TfToken &keyPath,
                      VtValueRef value);
 
    bool _ClearMetadata(const UsdObject &obj, const TfToken& fieldName,
                        const TfToken &keyPath=TfToken());
 
    // --------------------------------------------------------------------- //
    // Misc Internal Helpers
    // --------------------------------------------------------------------- //
 
    // Pcp helpers.
    PcpCache const *_GetPcpCache() const { return _cache.get(); }
    PcpCache *_GetPcpCache() { return _cache.get(); }
 
    // Returns the PrimIndex, using the read-only PcpCache API. We expect prims
    // to be composed during initial stage composition, so this method should
    // not be used in that context.
    const PcpPrimIndex* _GetPcpPrimIndex(const SdfPath& primPath) const;
 
    // Helper to report pcp errors.
    void _ReportPcpErrors(const PcpErrorVector &errors,
                          const std::string &context) const;
    void _ReportErrors(const PcpErrorVector &errors,
                       const std::vector<std::string>& otherErrors,
                       const std::string &context) const;
 
    // --------------------------------------------------------------------- //
    // Scenegraph Composition & Change Processing
    // --------------------------------------------------------------------- //
 
    // Compose the prim indexes in the subtrees rooted at the paths in 
    // \p primIndexPaths.  If \p instanceChanges is given, returns
    // changes to prototypes and instances due to the discovery of new instances
    // during composition.
    void _ComposePrimIndexesInParallel(
        const std::vector<SdfPath>& primIndexPaths,
        const std::string& context,
        Usd_InstanceChanges* instanceChanges = nullptr);
 
    // Recompose the subtree rooted at \p prim: compose its type, flags, and
    // list of children, then invoke _ComposeSubtree on all its children.
    void _ComposeSubtree(
        Usd_PrimDataPtr prim, Usd_PrimDataConstPtr parent,
        UsdStagePopulationMask const *mask,
        const SdfPath &primIndexPath = SdfPath());
    void _ComposeSubtreeImpl(
        Usd_PrimDataPtr prim, Usd_PrimDataConstPtr parent,
        UsdStagePopulationMask const *mask,
        const SdfPath &primIndexPath = SdfPath());
    void _ComposeSubtreesInParallel(
        const std::vector<Usd_PrimDataPtr> &prims,
        const std::vector<SdfPath> *primIndexPaths = nullptr);
 
    // Composes the full prim type info for the prim based on its type name
    // and applied API schemas.
    void _ComposePrimTypeInfoImpl(Usd_PrimDataPtr prim);
 
    // Compose subtree rooted at \p prim under \p parent.  This function
    // ensures that the appropriate prim index is specified for \p prim if
    // \p parent is in a prototype.
    void _ComposeChildSubtree(Usd_PrimDataPtr prim, 
                              Usd_PrimDataConstPtr parent,
                              UsdStagePopulationMask const *mask);
 
    // Compose \p prim's list of children and make any modifications necessary
    // to its _children member and the stage's _primMap, including possibly
    // instantiating new prims, or destroying existing subtrees of prims.  The
    // any newly created prims *do not* have their prim index, type, flags, or
    // children composed.
    //
    // Compose only \p prim's direct children if recurse=false.  Otherwise
    // recompose every descendent of \p prim.  Callers that pass recurse=false
    // should invoke _ComposeSubtree on any newly created prims to ensure caches
    // are correctly populated.
    void _ComposeChildren(Usd_PrimDataPtr prim,
                          UsdStagePopulationMask const *mask, bool recurse);
 
    // Instantiate a prim instance.  There must not already be an instance
    // at \p primPath.
    Usd_PrimDataPtr _InstantiatePrim(const SdfPath &primPath);
 
    // Instantiate a prototype prim and sets its parent to pseudoroot.  
    // There must not already be a prototype at \p primPath.
    Usd_PrimDataPtr _InstantiatePrototypePrim(const SdfPath &primPath);
 
    // For \p prim and all of its descendants, remove from _primMap and empty
    // their _children vectors.
    void _DestroyPrim(Usd_PrimDataPtr prim);
 
    // Destroy the prim subtrees rooted at each path in \p paths. \p paths may
    // not contain any path that is a descendent of another path in \p paths.
    void _DestroyPrimsInParallel(const std::vector<SdfPath>& paths);
 
    // Invoke _DestroyPrim() on all of \p prim's direct children.
    void _DestroyDescendents(Usd_PrimDataPtr prim);
 
    // Returns true if the object at the given path is a descendant of
    // an instance prim, i.e. a prim beneath an instance prim, or a property
    // of a prim beneath an instance prim.
    bool _IsObjectDescendantOfInstance(const SdfPath& path) const;
 
    // If the given prim is an instance, returns the corresponding 
    // prototype prim.  Otherwise, returns an invalid prim.
    Usd_PrimDataConstPtr _GetPrototypeForInstance(Usd_PrimDataConstPtr p) const;
 
    // Returns the path of the Usd prim using the prim index at the given path.
    SdfPath _GetPrimPathUsingPrimIndexAtPath(const SdfPath& primIndexPath) const;
 
    // Responds to LayersDidChangeSentPerLayer event and update stage contents 
    // in response to changes in scene description.
    void _HandleLayersDidChange(const SdfNotice::LayersDidChangeSentPerLayer &);
 
    // Pushes changes through PCP to determine invalidation based on 
    // composition metadata.
    // Note: This method will not perform any processing or notification
    // Refer to _ProcessPendingChanges()
    void _ComputePendingChanges(const SdfLayerChangeListVec &);
 
    // Update stage contents in response to changes to the asset resolver.
    void _HandleResolverDidChange(const ArNotice::ResolverChanged &);
 
    // Process stage change information stored in _pendingChanges.
    // _pendingChanges will be set to nullptr by the end of the function.
    // This function will return true if UsdNotice::ObjectsChanged and 
    // UsdNotice::StageContentsChanged notices were sent during execution.
    bool _ProcessPendingChanges();
 
    // Remove scene description for the prim at \p fullPath in the current edit
    // target.
    bool _RemovePrim(const SdfPath& fullPath);
 
    SdfPrimSpecHandle _GetPrimSpec(const SdfPath& fullPath);
 
    // Find and return the defining spec type for the property spec at the given
    // path, or SdfSpecTypeUnknown if none exists.  The defining spec type is
    // either the builtin definition's spec type, if the indicated property is
    // builtin, otherwise it's the strongest authored spec's type if one exists,
    // otherwise it's SdfSpecTypeUnknown.
    SdfSpecType _GetDefiningSpecType(Usd_PrimDataConstPtr primData,
                                     const TfToken &propName) const;
 
    // Helper to apply Pcp changes and recompose the scenegraph accordingly,
    // given an optional initial set of paths to recompose.
    void _Recompose(const PcpChanges &changes);
    template <class T>
    void _Recompose(const PcpChanges &changes, T *pathsToRecompose);
    template <class T>
    void _RecomposePrims(T *pathsToRecompose);
 
    // Helper for _Recompose to find the subtrees that need to be
    // fully recomposed and to recompose the name children of the
    // parents of these subtrees. Note that [start, finish) must be a
    // sorted range of map iterators whose keys are paths with no descendent
    // paths. In C++20, consider using the ranges API to improve this.
    template <class Iter>
    void _ComputeSubtreesToRecompose(Iter start, Iter finish,
                                     std::vector<Usd_PrimDataPtr>* recompose);
 
    // return true if the path is valid for load/unload operations.
    // This method will emit errors when invalid paths are encountered.
    bool _IsValidForLoad(const SdfPath& path) const;
    bool _IsValidForUnload(const SdfPath& path) const;
 
    // Discover all payloads in a given subtree, adding the path of each
    // discovered prim index to the \p primIndexPaths set. If specified,
    // the corresponding UsdPrim path will be added to the \p usdPrimPaths
    // set. The root path will be considered for inclusion in the result set.
    //
    // Note that some payloads may not be discoverable in until an ancestral
    // payload has been included. UsdStage::LoadAndUnload takes this into
    // account.
    void _DiscoverPayloads(const SdfPath& rootPath,
                           UsdLoadPolicy policy,
                           SdfPathSet* primIndexPaths,
                           bool unloadedOnly = false,
                           SdfPathSet* usdPrimPaths = nullptr) const;
 
    // ===================================================================== //
    //                          VALUE RESOLUTION                             //
    // ===================================================================== //
    // --------------------------------------------------------------------- //
    // Specialized Value Resolution
    // --------------------------------------------------------------------- //
 
    // Helpers for resolving values for metadata fields requiring
    // special behaviors.
    static SdfSpecifier _GetSpecifier(Usd_PrimDataConstPtr primData);
    static TfToken _GetKind(Usd_PrimDataConstPtr primData);
    static bool _IsActive(Usd_PrimDataConstPtr primData);
 
    // Custom is true if it is true anywhere in the stack.
    bool _IsCustom(const UsdProperty &prop) const;
 
    // Variability is determined by the weakest opinion in the stack.
    SdfVariability _GetVariability(const UsdProperty &prop) const;
 
    // Helper functions for resolving asset paths during value resolution.
    void _MakeResolvedAssetPaths(UsdTimeCode time, const UsdAttribute &attr,
                                 SdfAssetPath *assetPaths,
                                 size_t numAssetPaths,
                                 bool anchorAssetPathsOnly = false) const;
 
    void _MakeResolvedAssetPathsValue(UsdTimeCode time, const UsdAttribute &attr,
                                      VtValue *value,
                                      bool anchorAssetPathsOnly = false) const;
 
    void _MakeResolvedTimeCodes(UsdTimeCode time, const UsdAttribute &attr,
                                SdfTimeCode *timeCodes,
                                size_t numTimeCodes) const;
 
    void _MakeResolvedPathExpressions(
        UsdTimeCode time, const UsdAttribute &attr,
        SdfPathExpression *pathExprs,
        size_t numPathExprs) const;
 
    void _MakeResolvedAttributeValue(UsdTimeCode time, const UsdAttribute &attr,
                                     VtValue *value) const;
 
    // --------------------------------------------------------------------- //
    // Metadata Resolution
    // --------------------------------------------------------------------- //
 
public:
    // Trait that allows us to call the correct version of _GetMetadata for 
    // types that require type specific value resolution as opposed to just
    // strongest opinion. These types also use type specific resolution 
    // in _GetValue.
    template <class T>
    struct _HasTypeSpecificResolution {
        static const bool value =
            std::is_same<T, SdfAssetPath>::value ||
            std::is_same<T, VtArray<SdfAssetPath>>::value ||
            std::is_same<T, SdfTimeCode>::value ||
            std::is_same<T, VtArray<SdfTimeCode>>::value ||
            std::is_same<T, SdfPathExpression>::value ||
            std::is_same<T, VtArray<SdfPathExpression>>::value ||
            std::is_same<T, SdfTimeSampleMap>::value ||
            std::is_same<T, TsSpline>::value ||
            std::is_same<T, VtDictionary>::value;
    };
 
private:
    // Get metadata as a dynamically typed VtValue. Will perform type specific
    // value resolution if the returned held type requires it.
    USD_API
    bool _GetMetadata(const UsdObject &obj,
                      const TfToken& fieldName,
                      const TfToken &keyPath,
                      bool useFallbacks,
                      VtValue* result) const;
 
    USD_API
    bool _GetMetadata(const UsdObject &obj,
                      const TfToken& fieldName,
                      const TfToken &keyPath,
                      bool useFallbacks,
                      SdfAbstractDataValue *result,
                      bool strongestOnly) const;
 
    template <class T>
    bool _GetMetadata(const UsdObject &obj,
                      const TfToken& fieldName,
                      const TfToken &keyPath,
                      bool useFallbacks,
                      T* result) const {
        SdfAbstractDataTypedValue<T> out(result);
        const bool strongestOnly =
            !VtValueTypeCanCompose<std::decay_t<T>>::value &&
            !VtValueTypeCanTransform<std::decay_t<T>>::value;
        return _GetMetadata(obj, fieldName, keyPath, useFallbacks, &out,
                            strongestOnly);
    }
 
    template <class Composer>
    void _GetAttrTypeImpl(const UsdAttribute &attr,
                          const TfToken &fieldName,
                          bool useFallbacks,
                          Composer *composer) const;
 
    template <class Composer>
    void _GetAttrVariabilityImpl(const UsdAttribute &attr,
                                 bool useFallbacks,
                                 Composer *composer) const;
 
    template <class Composer>
    void _GetPropCustomImpl(const UsdProperty &prop,
                            bool useFallbacks,
                            Composer *composer) const;
 
    template <class Composer>
    bool _GetSpecialPropMetadataImpl(const UsdObject &obj,
                                     const TfToken &fieldName,
                                     const TfToken &keyPath,
                                     bool useFallbacks,
                                     Composer *composer) const;
    template <class Composer>
    bool _GetMetadataImpl(const UsdObject &obj,
                          const TfToken& fieldName,
                          const TfToken& keyPath,
                          bool includeFallbacks,
                          Composer *composer) const;
 
    template <class Composer>
    bool _GetGeneralMetadataImpl(const UsdObject &obj,
                                 const TfToken& fieldName,
                                 const TfToken& keyPath,
                                 bool includeFallbacks,
                                 Composer *composer) const;
 
    // NOTE: The "authoredOnly" flag is not yet in use, but when we have
    // support for prim-based metadata fallbacks, they should be ignored when
    // this flag is set to true.
    bool _HasMetadata(const UsdObject &obj, const TfToken& fieldName,
                      const TfToken &keyPath, bool useFallbacks) const;
 
    TfTokenVector
    _ListMetadataFields(const UsdObject &obj, bool useFallbacks) const;
 
    void _GetAllMetadata(const UsdObject &obj,
                         bool useFallbacks,
                         UsdMetadataValueMap* result,
                         bool anchorAssetPathsOnly = false) const;
 
    // --------------------------------------------------------------------- //
    // Default & TimeSample Resolution
    // --------------------------------------------------------------------- //
 
    void _GetResolveInfo(const UsdAttribute &attr, 
                         UsdResolveInfo *resolveInfo,
                         const UsdTimeCode *time = nullptr) const;
 
    void _GetResolveInfoWithResolveTarget(
        const UsdAttribute &attr, 
        const UsdResolveTarget &resolveTarget,
        UsdResolveInfo *resolveInfo,
        const UsdTimeCode *time = nullptr) const;
 
    template <class T> struct _ExtraResolveInfo;
 
    // Gets the value resolve info for the given attribute. If time is provided,
    // the resolve info is evaluated for that specific time (which may be 
    // default). Otherwise, if time is null, the resolve info is evaluated for
    // "any numeric time" and will not populate values in extraInfo that 
    // require a specific time to be evaluated.
    template <class T>
    void _GetResolveInfo(const UsdAttribute &attr, 
                         UsdResolveInfo *resolveInfo,
                         const UsdTimeCode *time = nullptr,
                         _ExtraResolveInfo<T> *extraInfo = nullptr) const;
 
    // Gets the value resolve info for the given attribute using the given 
    // resolve target. If time is provided, the resolve info is evaluated for 
    // that specific time (which may be default). Otherwise, if time is null, 
    // the resolve info is evaluated for "any numeric time" and will not 
    // populate values in extraInfo that require a specific time to be 
    // evaluated.
    template <class T>
    void _GetResolveInfoWithResolveTarget(
        const UsdAttribute &attr, 
        const UsdResolveTarget &resolveTarget,
        UsdResolveInfo *resolveInfo,
        const UsdTimeCode *time = nullptr,
        _ExtraResolveInfo<T> *extraInfo = nullptr) const;
 
    // Shared implementation function for _GetResolveInfo and 
    // _GetResolveInfoWithResolveTarget. The only difference between how these
    // two functions behave is in how they create the Usd_Resolver used for 
    // iterating over nodes and layers, thus they provide this implementation
    // with the needed MakeUsdResolverFn to create the Usd_Resolver.
    template <class T, class MakeUsdResolverFn>
    void _GetResolveInfoImpl(const UsdAttribute &attr, 
                         UsdResolveInfo *resolveInfo,
                         const UsdTimeCode *time,
                         _ExtraResolveInfo<T> *extraInfo,
                         const MakeUsdResolverFn &makeUsdResolveFn) const;
 
    template <class T> struct _ResolveInfoResolver;
    struct _PropertyStackResolver;
 
    template <class Resolver, class MakeUsdResolverFn>
    void _GetResolvedValueAtDefaultImpl(
        const UsdProperty &prop,
        Resolver *resolver,
        const MakeUsdResolverFn &makeUsdResolverFn) const;
 
    template <class Resolver, class MakeUsdResolverFn>
    void _GetResolvedValueAtTimeImpl(
        const UsdProperty &prop,
        Resolver *resolver,
        const UsdTimeCode *time,
        const MakeUsdResolverFn &makeUsdResolverFn) const;
 
    bool _GetValue(UsdTimeCode time, const UsdAttribute &attr, 
                   VtValue* result) const;
 
    template <class T>
    bool _GetValue(UsdTimeCode time, const UsdAttribute &attr,
                   T* result) const;
 
    template <class T>
    bool _GetValueImpl(UsdTimeCode time, const UsdAttribute &attr, 
                       Usd_InterpolatorBase* interpolator,
                       T* value) const;
 
    USD_API
    bool _GetValueFromResolveInfo(const UsdResolveInfo &info,
                                  UsdTimeCode time, const UsdAttribute &attr,
                                  VtValue* result) const;
 
    template <class T>
    USD_API
    bool _GetValueFromResolveInfo(const UsdResolveInfo &info,
                                  UsdTimeCode time, const UsdAttribute &attr,
                                  T* result) const;
 
    template <class T>
    bool _GetValueFromResolveInfoImpl(const UsdResolveInfo &info,
                                      UsdTimeCode time, const UsdAttribute &attr,
                                      Usd_InterpolatorBase* interpolator,
                                      T* value) const;
 
    template <class T>
    bool _GetDefaultValueFromResolveInfoImpl(const UsdResolveInfo &info,
                                             const UsdAttribute &attr,
                                             T* value) const;
 
    Usd_AssetPathContext
    _GetAssetPathContext(UsdTimeCode time, const UsdAttribute &attr) const;
 
    // --------------------------------------------------------------------- //
    // Specialized Time Sample I/O
    // --------------------------------------------------------------------- //
 
    bool _GetTimeSamplesInInterval(const UsdAttribute &attr,
                                   const GfInterval& interval,
                                   std::vector<double>* times) const;
 
    bool _GetTimeSamplesInIntervalFromResolveInfo(
                                   const UsdResolveInfo &info,
                                   const UsdAttribute &attr,
                                   const GfInterval& interval,
                                   std::vector<double>* times) const;
 
    size_t _GetNumTimeSamples(const UsdAttribute &attr) const;
 
    size_t _GetNumTimeSamplesFromResolveInfo(const UsdResolveInfo &info,
                                           const UsdAttribute &attr) const;
 
    bool _GetBracketingTimeSamples(const UsdAttribute &attr,
                                   double desiredTime,
                                   bool authoredOnly,
                                   double* lower,
                                   double* upper,
                                   bool* hasSamples) const;
 
    bool _GetBracketingTimeSamplesFromResolveInfo(const UsdResolveInfo &info,
                                                  const UsdAttribute &attr,
                                                  double desiredTime,
                                                  bool authoredOnly,
                                                  double* lower,
                                                  double* upper,
                                                  bool* hasSamples) const;
 
    bool _ValueMightBeTimeVarying(const UsdAttribute &attr) const;
 
    bool _ValueMightBeTimeVaryingFromResolveInfo(const UsdResolveInfo &info,
                                                 const UsdAttribute &attr) const;
 
    void _RegisterPerLayerNotices();
    void _RegisterResolverChangeNotice();
 
    // Helper to obtain a malloc tag string for this stage.
    inline char const *_GetMallocTagId() const;
 
private:
    class _PendingChanges;
 
    // Change block for use by the UsdNamespaceEditor to allow it to indicate
    // to its dependent stages what the expected namespace edits are when the
    // stages handles notices from the changes the namespace editor performs.
    // The stage uses this provide additional information about prim resyncs
    // related to namespace edits in the ObjectsChanged notice it sends.
    class _NamespaceEditsChangeBlock {
    public:
        // Info about an expected namespace edit change from UsdNamespaceEditor.
        // This includes the original pre-edit prim stack of the prim at the old
        // path which is used to determine if the prim at the new path has the
        // same composed contents after the edits as the prim had originally at
        // the old path before the edits.
        struct ExpectedNamespaceEditChange {
            SdfPath oldPath;
            SdfPath newPath;
            SdfPrimSpecHandleVector oldPrimStack;
        };
        using ExpectedNamespaceEditChangeVector = 
            std::vector<ExpectedNamespaceEditChange>;
 
        _NamespaceEditsChangeBlock(const UsdStagePtr &stage,
            ExpectedNamespaceEditChangeVector &&expectedChanges);
        _NamespaceEditsChangeBlock(_NamespaceEditsChangeBlock &&);
        ~_NamespaceEditsChangeBlock();
 
    private:
        UsdStagePtr _stage;
        std::unique_ptr<_PendingChanges> _localPendingChanges;
    };
 
    // The 'pseudo root' prim.
    Usd_PrimDataPtr _pseudoRoot;
 
    // The stage's root layer.
    SdfLayerRefPtr _rootLayer;
 
    // Every UsdStage has an implicit, in-memory session layer.
    // This is to allow for runtime overrides such as variant selections.
    SdfLayerRefPtr _sessionLayer;
 
    // The stage's EditTarget.
    UsdEditTarget _editTarget;
    bool _editTargetIsLocalLayer;
 
    std::unique_ptr<PcpCache> _cache;
    std::unique_ptr<Usd_ClipCache> _clipCache;
    std::unique_ptr<Usd_InstanceCache> _instanceCache;
 
    TfHashMap<TfToken, TfToken, TfHash> _invalidPrimTypeToFallbackMap;
 
    size_t _usedLayersRevision;
 
    // A concurrent map from Path to Prim, for fast random access.
    struct _TbbHashEq {
        inline bool equal(SdfPath const &l, SdfPath const &r) const {
            return l == r;
        }
        inline size_t hash(SdfPath const &path) const {
            return path.GetHash();
        }
    };
    using PathToNodeMap = tbb::concurrent_hash_map<
        SdfPath, Usd_PrimDataIPtr, _TbbHashEq>;
    PathToNodeMap _primMap;
 
    // The interpolation type used for all attributes on the stage.
    UsdInterpolationType _interpolationType;
 
    typedef std::vector<
        std::pair<SdfLayerHandle, TfNotice::Key> > _LayerAndNoticeKeyVec;
    _LayerAndNoticeKeyVec _layersAndNoticeKeys;
    size_t _lastChangeSerialNumber;
 
    TfNotice::Key _resolverChangeKey;
 
    // Data for pending change processing.
    _PendingChanges* _pendingChanges;
 
    std::optional<WorkDispatcher> _dispatcher;
 
    // To provide useful aggregation of malloc stats, we bill everything
    // for this stage - from all access points - to this tag.
    std::unique_ptr<std::string> _mallocTagID;
 
    // The state used when instantiating the stage.
    const InitialLoadSet _initialLoadSet;
 
    // The population mask that applies to this stage.
    UsdStagePopulationMask _populationMask;
    
    // The load rules that apply to this stage.
    UsdStageLoadRules _loadRules;
    
    bool _isClosingStage;
    bool _isWritingFallbackPrimTypes;
 
    friend class UsdAPISchemaBase;
    friend class UsdAttribute;
    friend class UsdAttributeQuery;
    friend class UsdEditTarget;
    friend class UsdInherits;
    friend class UsdNamespaceEditor;
    friend class UsdObject;
    friend class UsdPrim;
    friend class UsdProperty;
    friend class UsdRelationship;
    friend class UsdSpecializes;
    friend class UsdVariantSet;
    friend class UsdVariantSets;
    friend class Usd_AssetPathContext;
    friend class Usd_FlattenAccess;
    friend class Usd_PcpCacheAccess;
    friend class Usd_PrimData;
    friend class Usd_StageOpenRequest;
    friend class Usd_TypeQueryAccess;
    template <class T> friend struct Usd_AttrGetValueHelper;
    friend struct Usd_AttrGetUntypedValueHelper;
    template <class RefsOrPayloadsEditorType, class RefsOrPayloadsProxyType> 
        friend struct Usd_ListEditImpl;
};
 
template<typename T>
bool
UsdStage::GetMetadata(const TfToken& key, T* value) const
{
    VtValue result;
    if (!GetMetadata(key, &result)){
        return false;
    }
 
    if (result.IsHolding<T>()){
        *value = result.UncheckedGet<T>();
        return true;
    } else {
        TF_CODING_ERROR("Requested type %s for stage metadatum %s does not"
                        " match retrieved type %s",
                        ArchGetDemangled<T>().c_str(),
                        key.GetText(),
                        result.GetTypeName().c_str());
        return false;
    }
}
 
template<typename T>
bool
UsdStage::GetMetadataByDictKey(const TfToken& key, const TfToken &keyPath, 
                               T* value) const
{
    VtValue result;
    if (!GetMetadataByDictKey(key, keyPath, &result)){
        return false;
    }
 
    if (result.IsHolding<T>()){
        *value = result.UncheckedGet<T>();
        return true;
    } else {
        TF_CODING_ERROR("Requested type %s for stage metadatum %s[%s] does not"
                        " match retrieved type %s",
                        ArchGetDemangled<T>().c_str(),
                        key.GetText(),
                        keyPath.GetText(),
                        result.GetTypeName().c_str());
        return false;
    }
}
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif //PXR_USD_USD_STAGE_H