stage.h

Go to the documentation of this file.

//
// Copyright 2016 Pixar
//
// Licensed under the Apache License, Version 2.0 (the "Apache License")
// with the following modification; you may not use this file except in
// compliance with the Apache License and the following modification to it:
// Section 6. Trademarks. is deleted and replaced with:
//
// 6. Trademarks. This License does not grant permission to use the trade
//    names, trademarks, service marks, or product names of the Licensor
//    and its affiliates, except as required to comply with Section 4(c) of
//    the License and to reproduce the content of the NOTICE file.
//
// You may obtain a copy of the Apache License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the Apache License with the above modification is
// distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the Apache License for the specific
// language governing permissions and limitations under the Apache 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/primFlags.h"

#include "pxr/base/tf/declarePtrs.h"
#include "pxr/base/tf/hashmap.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/pcp/cache.h"
#include "pxr/base/vt/value.h"
#include "pxr/base/work/dispatcher.h"

#include <boost/optional.hpp>

#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 <unordered_map>
#include <utility>

PXR_NAMESPACE_OPEN_SCOPE


class ArResolverContext;
class GfInterval;
class SdfAbstractDataValue;
class Usd_ClipCache;
class Usd_InstanceCache;
class Usd_InstanceChanges;
class Usd_InterpolatorBase;
class UsdResolveInfo;
class UsdResolveTarget;
class Usd_Resolver;
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(
        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
    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;

    template<typename T>
    bool SetMetadata(const TfToken &key, const T &value) const;
    USD_API
    bool SetMetadata(const TfToken &key, const VtValue &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;

    template<typename T>
    bool SetMetadataByDictKey(const TfToken& key, const TfToken &keyPath, 
                              const T& value) const;
    USD_API
    bool SetMetadataByDictKey(
        const TfToken& key, const TfToken &keyPath, const VtValue& 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);

    SdfPropertySpecHandle
    _GetSchemaPropertySpec(const UsdPrim &prim, const TfToken &propName) const;

    SdfPropertySpecHandle
    _GetSchemaPropertySpec(const UsdProperty &prop) const;

    template <class PropType>
    SdfHandle<PropType>
    _GetSchemaPropertySpec(const UsdProperty &prop) const;

    SdfAttributeSpecHandle
    _GetSchemaAttributeSpec(const UsdAttribute &attr) const;

    SdfRelationshipSpecHandle
    _GetSchemaRelationshipSpec(const UsdRelationship &rel) const;

    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
    // --------------------------------------------------------------------- //

    // Trait that allows us to call the correct versions of _SetValue and 
    // _SetMetadata for types whose values need to be mapped when written to
    // different edit targets.
    template <class T>
    struct _IsEditTargetMappable {
        static const bool value =
            std::is_same<T, SdfTimeCode>::value ||
            std::is_same<T, VtArray<SdfTimeCode>>::value ||
            std::is_same<T, SdfTimeSampleMap>::value ||
            std::is_same<T, VtDictionary>::value;
    };

    // Set value for types that don't need to be mapped for edit targets.
    template <class T>
    typename std::enable_if<!_IsEditTargetMappable<T>::value, bool>::type
    _SetValue(
        UsdTimeCode time, const UsdAttribute &attr, const T &newValue);

    // Set value for types that do need to be mapped for edit targets.
    template <class T>
    typename std::enable_if<_IsEditTargetMappable<T>::value, bool>::type
    _SetValue(
        UsdTimeCode time, const UsdAttribute &attr, const T &newValue);

    // Set value for dynamically typed VtValue. Will map the value across edit
    // targets if the held value type supports it.
    bool _SetValue(
        UsdTimeCode time, const UsdAttribute &attr, const VtValue &newValue);

    template <class T>
    bool _SetEditTargetMappedValue(
        UsdTimeCode time, const UsdAttribute &attr, const T &newValue);

    template <class T>
    bool _SetValueImpl(
        UsdTimeCode time, const UsdAttribute &attr, const T& value);

    bool _ClearValue(UsdTimeCode time, const UsdAttribute &attr);

    // Set metadata for types that don't need to be mapped across edit targets.
    template <class T>
    typename std::enable_if<!_IsEditTargetMappable<T>::value, bool>::type
    _SetMetadata(const UsdObject &object, const TfToken& key,
                 const TfToken &keyPath, const T& value);

    // Set metadata for types that do need to be mapped for edit targets.
    template <class T>
    typename std::enable_if<_IsEditTargetMappable<T>::value, bool>::type
    _SetMetadata(const UsdObject &object, const TfToken& key,
                 const TfToken &keyPath, const T& value);

    // Set metadata for dynamically typed VtValue. Will map the value across 
    // edit targets if the held value type supports it.
    USD_API
    bool _SetMetadata(const UsdObject &object,
                      const TfToken& key,
                      const TfToken &keyPath,
                      const VtValue& value);

    template <class T>
    bool _SetEditTargetMappedMetadata(
        const UsdObject &obj, const TfToken& fieldName,
        const TfToken &keyPath, const T &newValue);

    template <class T>
    bool _SetMetadataImpl(
        const UsdObject &obj, const TfToken& fieldName,
        const TfToken &keyPath, const T &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);

    // 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;

    // Update stage contents in response to changes in scene description.
    void _HandleLayersDidChange(const SdfNotice::LayersDidChangeSentPerLayer &);

    // 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.
    void _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 paths with no descendent paths.
    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 _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, SdfTimeSampleMap>::value ||
            std::is_same<T, VtDictionary>::value;
    };

private:
    // Get metadata for types that do not have type specific value resolution.
    template <class T>
    typename std::enable_if<!_HasTypeSpecificResolution<T>::value, bool>::type
    _GetMetadata(const UsdObject &obj,
                 const TfToken& fieldName,
                 const TfToken &keyPath,
                 bool useFallbacks,
                 T* result) const;

    // Get metadata for types that do have type specific value resolution.
    template <class T>
    typename std::enable_if<_HasTypeSpecificResolution<T>::value, bool>::type
    _GetMetadata(const UsdObject &obj,
                 const TfToken& fieldName,
                 const TfToken &keyPath,
                 bool useFallbacks,
                 T* result) const;

    // Get metadata as a dynamically typed VtValue. Will perform type specific
    // value resolution if the returned held type requires it.
    bool _GetMetadata(const UsdObject &obj,
                      const TfToken& fieldName,
                      const TfToken &keyPath,
                      bool useFallbacks,
                      VtValue* result) const;

    // Gets a metadata value using only strongest value resolution. It is 
    // assumed that result is holding a value that does not require type 
    // specific value resolution.
    USD_API
    bool _GetStrongestResolvedMetadata(const UsdObject &obj,
                                       const TfToken& fieldName,
                                       const TfToken &keyPath,
                                       bool useFallbacks,
                                       SdfAbstractDataValue* result) const;

    // Gets a metadata value with the type specific value resolution for the 
    // type applied. This is only implemented for types that 
    // _HasTypeSpecificResolution.
    template <class T>
    USD_API
    bool _GetTypeSpecificResolvedMetadata(const UsdObject &obj,
                                          const TfToken& fieldName,
                                          const TfToken &keyPath,
                                          bool useFallbacks,
                                          T* result) const;

    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 double *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;

    SdfLayerRefPtr
    _GetLayerWithStrongestValue(
        UsdTimeCode time, const UsdAttribute &attr) 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;

    // --------------------------------------------------------------------- //
    // 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:

    // 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.
    class _PendingChanges;
    _PendingChanges* _pendingChanges;

    boost::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 UsdObject;
    friend class UsdPrim;
    friend class UsdProperty;
    friend class UsdRelationship;
    friend class UsdSpecializes;
    friend class UsdVariantSet;
    friend class UsdVariantSets;
    friend class Usd_FlattenAccess;
    friend class Usd_PcpCacheAccess;
    friend class Usd_PrimData;
    friend class Usd_StageOpenRequest;
    template <class T> friend struct Usd_AttrGetValueHelper;
    friend struct Usd_AttrGetUntypedValueHelper;
    template <class RefsOrPayloadsEditorType, class RefsOrPayloadsProxyType> 
        friend struct Usd_ListEditImpl;
};

// UsdObject's typed metadata query relies on this specialization being
// externally visible and exporting the primary template does not
// automatically export this specialization.
template <>
USD_API
bool
UsdStage::_GetTypeSpecificResolvedMetadata(const UsdObject &obj,
                                           const TfToken& fieldName,
                                           const TfToken &keyPath,
                                           bool useFallbacks,
                                           SdfTimeSampleMap* result) const;

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::SetMetadata(const TfToken& key, const T& value) const
{
    VtValue in(value);
    return SetMetadata(key, in);
}

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;
    }
}

template<typename T>
bool 
UsdStage::SetMetadataByDictKey(const TfToken& key, const TfToken &keyPath, 
                               const T& value) const
{
    VtValue in(value);
    return SetMetadataByDictKey(key, keyPath, in);
}

// Get metadata for types that do not have type specific value resolution.
template <class T>
typename std::enable_if<
    !UsdStage::_HasTypeSpecificResolution<T>::value, bool>::type
UsdStage::_GetMetadata(const UsdObject &obj,
                       const TfToken& fieldName,
                       const TfToken &keyPath,
                       bool useFallbacks,
                       T* result) const
{
    // Since these types don't have type specific value resolution, we can just 
    // get the strongest metadata value and be done.
    SdfAbstractDataTypedValue<T> out(result);
    return _GetStrongestResolvedMetadata(
        obj, fieldName, keyPath, useFallbacks, &out);
}

// Get metadata for types that do have type specific value resolution.
template <class T>
typename std::enable_if<
    UsdStage::_HasTypeSpecificResolution<T>::value, bool>::type
UsdStage::_GetMetadata(const UsdObject &obj,
                       const TfToken& fieldName,
                       const TfToken &keyPath,
                       bool useFallbacks,
                       T* result) const
{
    // Call the templated type specifice resolved metadata implementation that 
    // will only be implemented for types that support it.
    return _GetTypeSpecificResolvedMetadata(
        obj, fieldName, keyPath, useFallbacks, result);
}


// Set metadata for types that don't need to be mapped across edit targets.
template <class T>
typename std::enable_if<!UsdStage::_IsEditTargetMappable<T>::value, bool>::type
UsdStage::_SetMetadata(const UsdObject &object, const TfToken& key,
                       const TfToken &keyPath, const T& value)
{
    // Since we know that we don't need to map the value for edit targets, 
    // we can just type erase the value and set the metadata as is.
    SdfAbstractDataConstTypedValue<T> in(&value);
    return _SetMetadataImpl<SdfAbstractDataConstValue>(
        object, key, keyPath, in);
}

// Set metadata for types that do need to be mapped for edit targets.
template <class T>
typename std::enable_if<UsdStage::_IsEditTargetMappable<T>::value, bool>::type
UsdStage::_SetMetadata(const UsdObject &object, const TfToken& key,
                       const TfToken &keyPath, const T& value)
{
    return _SetEditTargetMappedMetadata(object, key, keyPath, value);
}


PXR_NAMESPACE_CLOSE_SCOPE

#endif //PXR_USD_USD_STAGE_H