layer.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_SDF_LAYER_H
#define PXR_USD_SDF_LAYER_H
 
 
#include "pxr/pxr.h"
#include "pxr/usd/sdf/api.h"
#include "pxr/usd/sdf/data.h"
#include "pxr/usd/sdf/declareHandles.h"
#include "pxr/usd/sdf/identity.h"
#include "pxr/usd/sdf/layerHints.h"
#include "pxr/usd/sdf/layerOffset.h"
#include "pxr/usd/sdf/namespaceEdit.h"
#include "pxr/usd/sdf/path.h"
#include "pxr/usd/sdf/proxyTypes.h"
#include "pxr/usd/sdf/spec.h"
#include "pxr/usd/sdf/types.h"
#include "pxr/usd/ar/ar.h"
#include "pxr/usd/ar/assetInfo.h"
#include "pxr/usd/ar/resolvedPath.h"
#include "pxr/base/tf/declarePtrs.h"
#include "pxr/base/vt/value.h"
#include "pxr/base/work/dispatcher.h"
 
#include <atomic>
#include <functional>
#include <memory>
#include <optional>
#include <set>
#include <string>
#include <vector>
 
PXR_NAMESPACE_OPEN_SCOPE
 
TF_DECLARE_WEAK_PTRS(SdfFileFormat);
TF_DECLARE_WEAK_AND_REF_PTRS(SdfLayerStateDelegateBase);
 
class SdfChangeList;
struct Sdf_AssetInfo;
 
class SdfLayer 
    : public TfRefBase
    , public TfWeakBase
{
public:
    SDF_API
    virtual ~SdfLayer(); 
 
    SdfLayer(const SdfLayer&) = delete;
    SdfLayer& operator=(const SdfLayer&) = delete;
 
 
    SDF_API const SdfSchemaBase& GetSchema() const;
 
    SDF_API const SdfFileFormatConstPtr& GetFileFormat() const;
 
    typedef std::map<std::string, std::string> FileFormatArguments;
 
    SDF_API const FileFormatArguments& GetFileFormatArguments() const;
 
    SDF_API
    static SdfLayerRefPtr CreateNew(const std::string &identifier,
                                    const FileFormatArguments &args =
                                    FileFormatArguments());
 
    SDF_API
    static SdfLayerRefPtr CreateNew(const SdfFileFormatConstPtr& fileFormat,
                                    const std::string &identifier,
                                    const FileFormatArguments &args =
                                    FileFormatArguments());
 
    SDF_API
    static SdfLayerRefPtr New(const SdfFileFormatConstPtr& fileFormat,
                              const std::string &identifier,
                              const FileFormatArguments &args = 
                              FileFormatArguments());
 
    SDF_API
    static SdfLayerHandle Find(
        const std::string &identifier,
        const FileFormatArguments &args = FileFormatArguments());
 
    SDF_API
    static SdfLayerHandle FindRelativeToLayer(
        const SdfLayerHandle &anchor,
        const std::string &identifier,
        const FileFormatArguments &args = FileFormatArguments());
 
    SDF_API
    static SdfLayerRefPtr FindOrOpen(
        const std::string &identifier,
        const FileFormatArguments &args = FileFormatArguments());
 
    SDF_API
    static SdfLayerRefPtr FindOrOpenRelativeToLayer(
        const SdfLayerHandle &anchor,
        const std::string &identifier,
        const FileFormatArguments &args = FileFormatArguments());
        
    SDF_API
    static SdfLayerRefPtr OpenAsAnonymous(
        const std::string &layerPath,
        bool metadataOnly = false,
        const std::string& tag = std::string());
 
    SDF_API
    SdfDataRefPtr GetMetadata() const;
 
    SDF_API
    SdfLayerHints GetHints() const;
 
    SDF_API
    static SdfLayerHandleSet GetLoadedLayers();
 
    SDF_API
    bool IsEmpty() const;
 
    SDF_API
    bool StreamsData() const;
 
    SDF_API
    bool IsDetached() const;
 
    SDF_API
    void TransferContent(const SdfLayerHandle& layer);
 
    SDF_API
    static SdfLayerRefPtr CreateAnonymous(
        const std::string& tag = std::string(),
        const FileFormatArguments& args = FileFormatArguments());
 
    SDF_API
    static SdfLayerRefPtr CreateAnonymous(
        const std::string &tag, const SdfFileFormatConstPtr &format,
        const FileFormatArguments& args = FileFormatArguments());
 
    SDF_API
    bool IsAnonymous() const;
 
    SDF_API
    static bool IsAnonymousLayerIdentifier(const std::string& identifier);
 
    SDF_API
    static std::string GetDisplayNameFromIdentifier(
        const std::string& identifier);
 
 
    SDF_API
    bool Save(bool force = false) const;
 
    SDF_API
    bool Export(const std::string& filename, 
                const std::string& comment = std::string(),
                const FileFormatArguments& args = FileFormatArguments()) const;
 
    SDF_API
    bool ExportToString(std::string* result) const;
 
    SDF_API
    bool ImportFromString(const std::string &string);
 
    SDF_API
    void Clear();
 
    SDF_API
    bool Reload(bool force = false);
 
    SDF_API
    static bool ReloadLayers(const std::set<SdfLayerHandle>& layers,
                             bool force = false);
 
    SDF_API
    bool Import(const std::string &layerPath);
 
 
    SDF_API
    std::set<std::string> GetExternalReferences() const;
 
    SDF_API
    bool UpdateExternalReference(
        const std::string &oldAssetPath,
        const std::string &newAssetPath=std::string());
 
    SDF_API
    std::set<std::string> GetCompositionAssetDependencies() const;
 
    SDF_API
    bool UpdateCompositionAssetDependency(
        const std::string &oldAssetPath,
        const std::string &newAssetPath=std::string());
 
    SDF_API
    std::set<std::string> GetExternalAssetDependencies() const;
 
 
    SDF_API
    static bool SplitIdentifier(
        const std::string& identifier,
        std::string* layerPath,
        FileFormatArguments* arguments);
 
    SDF_API
    static std::string CreateIdentifier(
        const std::string& layerPath,
        const FileFormatArguments& arguments);
 
    SDF_API
    const std::string& GetIdentifier() const;
 
    SDF_API
    void SetIdentifier(const std::string& identifier);
 
    SDF_API
    void UpdateAssetInfo();
 
    SDF_API
    std::string GetDisplayName() const;
 
    SDF_API
    const ArResolvedPath& GetResolvedPath() const;
 
    SDF_API
    const std::string& GetRealPath() const;
 
    SDF_API
    std::string GetFileExtension() const;
 
    SDF_API
    const std::string& GetVersion() const;
 
    SDF_API
    const std::string& GetRepositoryPath() const;
 
    SDF_API
    const std::string& GetAssetName() const;
 
    SDF_API
    const VtValue& GetAssetInfo() const;
 
    SDF_API
    std::string ComputeAbsolutePath(const std::string& assetPath) const;
 
 
 
    SDF_API
    SdfSpecType GetSpecType(const SdfPath& path) const;
 
    SDF_API
    bool HasSpec(const SdfPath& path) const;
 
    SDF_API
    std::vector<TfToken> ListFields(const SdfPath& path) const;
 
    SDF_API
    bool HasField(const SdfPath& path, const TfToken& fieldName,
                  VtValue *value=NULL) const;
    SDF_API
    bool HasField(const SdfPath& path, const TfToken& fieldName,
                  SdfAbstractDataValue *value) const;
 
    template <class T>
    bool HasField(const SdfPath& path, const TfToken &name, 
        T* value) const
    {
        if (!value) {
            return HasField(path, name, static_cast<VtValue *>(NULL));
        }
 
        SdfAbstractDataTypedValue<T> outValue(value);
        const bool hasValue = HasField(
            path, name, static_cast<SdfAbstractDataValue *>(&outValue));
 
        if (std::is_same<T, SdfValueBlock>::value) {
            return hasValue && outValue.isValueBlock;
        }
 
        return hasValue && (!outValue.isValueBlock);
    }
 
    std::type_info const &GetFieldTypeid(
        const SdfPath &path, const TfToken &name) const {
        return _data->GetTypeid(path, name);
    }
 
    SDF_API
    bool HasFieldDictKey(const SdfPath& path,
                         const TfToken &fieldName,
                         const TfToken &keyPath,
                         VtValue *value=NULL) const;
    SDF_API
    bool HasFieldDictKey(const SdfPath& path,
                         const TfToken &fieldName,
                         const TfToken &keyPath,
                         SdfAbstractDataValue *value) const;
 
    template <class T>
    bool HasFieldDictKey(const SdfPath& path, const TfToken &name,
                         const TfToken &keyPath, T* value) const
    {
        if (!value) {
            return HasFieldDictKey(path, name, keyPath,
                                   static_cast<VtValue *>(NULL));
        }
 
        SdfAbstractDataTypedValue<T> outValue(value);
        return HasFieldDictKey(path, name, keyPath,
                               static_cast<SdfAbstractDataValue *>(&outValue));
    }
 
 
    SDF_API
    VtValue GetField(const SdfPath& path,
                     const TfToken& fieldName) const;
 
    template <class T>
    inline T GetFieldAs(const SdfPath& path, 
        const TfToken& fieldName, const T& defaultValue = T()) const
    {
        return _data->GetAs<T>(path, fieldName, defaultValue);
    }
 
    SDF_API
    VtValue GetFieldDictValueByKey(const SdfPath& path,
                                   const TfToken& fieldName,
                                   const TfToken& keyPath) const;
 
    SDF_API
    void SetField(const SdfPath& path, const TfToken& fieldName,
        const VtValue& value);
    SDF_API
    void SetField(const SdfPath& path, const TfToken& fieldName,
        const SdfAbstractDataConstValue& value);
 
    template <class T>
    void SetField(const SdfPath& path, const TfToken& fieldName, 
        const T& val) 
    {
        // Ideally, this would make use of the SdfAbstractDataConstValue
        // API to avoid unnecessarily copying the value into a VtValue.
        // However, Sdf needs to create a VtValue for change processing.
        // If the underlying SdAbstractData implementation also needs a 
        // VtValue, using the SdfAbstractDataConstValue API would cause
        // another copy to be made. So, it's more efficient to just create 
        // the VtValue once here and push that along.
        SetField(path, fieldName, VtValue(val));
    }
 
    SDF_API
    void SetFieldDictValueByKey(const SdfPath& path,
                                const TfToken& fieldName,
                                const TfToken& keyPath,
                                const VtValue& value);
    SDF_API
    void SetFieldDictValueByKey(const SdfPath& path,
                                const TfToken& fieldName,
                                const TfToken& keyPath,
                                const SdfAbstractDataConstValue& value);
 
    template <class T>
    void SetFieldDictValueByKey(const SdfPath& path,
                                const TfToken& fieldName,
                                const TfToken& keyPath,
                                const T& val)
    {
        // Ideally, this would make use of the SdfAbstractDataConstValue
        // API to avoid unnecessarily copying the value into a VtValue.
        // However, Sdf needs to create a VtValue for change processing.
        // If the underlying SdAbstractData implementation also needs
        // VtValue, using the SdfAbstractDataConstValue API would cause
        // another copy to be made. So, it's more efficient to just create
        // the VtValue once here and push that along.
        SetFieldDictValueByKey(path, fieldName, keyPath, VtValue(val));
    }
 
    SDF_API
    void EraseField(const SdfPath& path, const TfToken& fieldName);
 
    SDF_API
    void EraseFieldDictValueByKey(const SdfPath& path,
                                  const TfToken& fieldName,
                                  const TfToken& keyPath);
 
 
    typedef std::function<void(const SdfPath&)> TraversalFunction;
 
    // Traverse will perform a traversal of the scene description hierarchy
    // rooted at \a path, calling \a func on each spec that it finds.
    SDF_API
    void Traverse(const SdfPath& path, const TraversalFunction& func);
 
 
 
    SDF_API
    SdfAssetPath GetColorConfiguration() const;
 
    SDF_API
    void SetColorConfiguration(const SdfAssetPath &colorConfiguration);
 
    SDF_API 
    bool HasColorConfiguration() const;
    
    SDF_API
    void ClearColorConfiguration();
 
    SDF_API
    TfToken GetColorManagementSystem() const;
 
    SDF_API
    void SetColorManagementSystem(const TfToken &cms);
 
    SDF_API 
    bool HasColorManagementSystem() const;
    
    SDF_API
    void ClearColorManagementSystem();
 
    SDF_API
    std::string GetComment() const;
 
    SDF_API
    void SetComment(const std::string &comment);
    
    SDF_API
    TfToken GetDefaultPrim() const;
 
    SDF_API
    SdfPath GetDefaultPrimAsPath() const;
 
    SDF_API
    void SetDefaultPrim(const TfToken &name);
 
    SDF_API
    void ClearDefaultPrim();
 
    SDF_API
    bool HasDefaultPrim();
 
    SDF_API
    static SdfPath ConvertDefaultPrimTokenToPath(const TfToken &defaultPrim);
 
    SDF_API
    static TfToken ConvertDefaultPrimPathToToken(const SdfPath &primPath);
 
    SDF_API
    std::string GetDocumentation() const;
 
    SDF_API
    void SetDocumentation(const std::string &documentation);
 
    SDF_API
    double GetStartTimeCode() const;
 
    SDF_API
    void SetStartTimeCode(double startTimecode);
 
    SDF_API
    bool HasStartTimeCode() const;
 
    SDF_API
    void ClearStartTimeCode();
    
    SDF_API
    double GetEndTimeCode() const;
 
    SDF_API
    void SetEndTimeCode(double endTimeCode);
 
    SDF_API
    bool HasEndTimeCode() const;
 
    SDF_API
    void ClearEndTimeCode();
    
    SDF_API
    double GetTimeCodesPerSecond() const;
 
    SDF_API
    void SetTimeCodesPerSecond(double timeCodesPerSecond);
 
    SDF_API
    bool HasTimeCodesPerSecond() const;
 
    SDF_API
    void ClearTimeCodesPerSecond();
 
    SDF_API
    double GetFramesPerSecond() const;
 
    SDF_API
    void SetFramesPerSecond(double framesPerSecond);
 
    SDF_API
    bool HasFramesPerSecond() const;
 
    SDF_API
    void ClearFramesPerSecond();
    
    SDF_API
    int GetFramePrecision() const;
 
    SDF_API
    void SetFramePrecision(int framePrecision);
 
    SDF_API
    bool HasFramePrecision() const;
 
    SDF_API
    void ClearFramePrecision();
 
    SDF_API
    std::string GetOwner() const;
 
    SDF_API
    void SetOwner(const std::string& owner);
 
    SDF_API
    bool HasOwner() const;
 
    SDF_API
    void ClearOwner();
 
    SDF_API
    std::string GetSessionOwner() const;
 
    SDF_API
    void SetSessionOwner(const std::string& owner);
 
    SDF_API
    bool HasSessionOwner() const;
 
    // Clear the session owner opinion.
    SDF_API
    void ClearSessionOwner();
 
    SDF_API
    bool GetHasOwnedSubLayers() const;
 
    SDF_API
    void SetHasOwnedSubLayers(bool);
 
    SDF_API
    VtDictionary GetCustomLayerData() const;
 
    SDF_API
    void SetCustomLayerData(const VtDictionary& value);
 
    SDF_API
    bool HasCustomLayerData() const;
 
    SDF_API
    void ClearCustomLayerData();
 
    SDF_API
    VtDictionary GetExpressionVariables() const;
    
    SDF_API
    void SetExpressionVariables(const VtDictionary& expressionVars);
 
    SDF_API
    bool HasExpressionVariables() const;
 
    SDF_API
    void ClearExpressionVariables();
 
 
    // Type for root prims view.
    typedef SdfPrimSpecView RootPrimsView;
 
    SDF_API
    RootPrimsView GetRootPrims() const;
 
    SDF_API
    void SetRootPrims(const SdfPrimSpecHandleVector &rootPrims);
 
    SDF_API
    bool InsertRootPrim(const SdfPrimSpecHandle &prim, int index = -1);
 
    SDF_API
    void RemoveRootPrim(const SdfPrimSpecHandle &prim);
 
    SDF_API
    void ScheduleRemoveIfInert(const SdfSpec& spec);
 
    SDF_API
    void RemovePrimIfInert(SdfPrimSpecHandle prim);
 
    SDF_API
    void RemovePropertyIfHasOnlyRequiredFields(SdfPropertySpecHandle prop);
 
    SDF_API
    void RemoveInertSceneDescription();
 
    SDF_API
    SdfNameOrderProxy GetRootPrimOrder() const;
   
    SDF_API
    void SetRootPrimOrder(const std::vector<TfToken>& names);
 
    SDF_API
    void InsertInRootPrimOrder(const TfToken &name, int index = -1);
 
    SDF_API
    void RemoveFromRootPrimOrder(const TfToken & name);
 
    SDF_API
    void RemoveFromRootPrimOrderByIndex(int index);
 
    SDF_API
    void ApplyRootPrimOrder(std::vector<TfToken> *vec) const;
 
 
    SDF_API
    SdfSubLayerProxy GetSubLayerPaths() const;
 
    SDF_API
    void SetSubLayerPaths(const std::vector<std::string>& newPaths);
 
    SDF_API
    size_t GetNumSubLayerPaths() const;
 
    SDF_API
    void InsertSubLayerPath(const std::string& path, int index = -1);
 
    SDF_API
    void RemoveSubLayerPath(int index);
 
    SDF_API
    SdfLayerOffsetVector GetSubLayerOffsets() const;
 
    SDF_API
    SdfLayerOffset GetSubLayerOffset(int index) const;
 
    SDF_API
    void SetSubLayerOffset(const SdfLayerOffset& offset, int index);
 
 
    SDF_API
    SdfRelocates GetRelocates() const;
    
    SDF_API
    void SetRelocates(const SdfRelocates& relocates);
 
    SDF_API
    bool HasRelocates() const;
    
    SDF_API
    void ClearRelocates();
 
 
 
    class DetachedLayerRules
    {
    public:
        DetachedLayerRules() = default;
 
        DetachedLayerRules& IncludeAll() 
        { 
            _includeAll = true; 
            _include.clear();
            return *this; 
        }
 
        SDF_API
        DetachedLayerRules& Include(const std::vector<std::string>& patterns);
 
        SDF_API
        DetachedLayerRules& Exclude(const std::vector<std::string>& patterns);
 
        bool IncludedAll() const { return _includeAll; }
        const std::vector<std::string>& GetIncluded() const { return _include; }
        const std::vector<std::string>& GetExcluded() const { return _exclude; }
 
        SDF_API
        bool IsIncluded(const std::string& identifier) const;
 
    private:
        friend class SdfLayer;
 
        std::vector<std::string> _include;
        std::vector<std::string> _exclude;
        bool _includeAll = false;
    };
 
    SDF_API
    static void SetDetachedLayerRules(const DetachedLayerRules& mask);
 
    SDF_API
    static const DetachedLayerRules& GetDetachedLayerRules();
 
    SDF_API
    static bool IsIncludedByDetachedLayerRules(const std::string& identifier);
 
 
 
    SDF_API
    static std::set<std::string> GetMutedLayers();
 
    SDF_API
    bool IsMuted() const;
 
    SDF_API
    static bool IsMuted(const std::string &path);
 
    SDF_API
    void SetMuted(bool muted);
 
    SDF_API
    static void AddToMutedLayers(const std::string &mutedPath);
 
    SDF_API
    static void RemoveFromMutedLayers(const std::string &mutedPath);
 
 
    SDF_API
    SdfPrimSpecHandle GetPseudoRoot() const;
 
    SDF_API
    SdfSpecHandle GetObjectAtPath(const SdfPath &path);
 
    SDF_API
    SdfPrimSpecHandle GetPrimAtPath(const SdfPath &path);
 
    SDF_API
    SdfPropertySpecHandle GetPropertyAtPath(const SdfPath &path);
 
    SDF_API
    SdfAttributeSpecHandle GetAttributeAtPath(const SdfPath &path);
 
    SDF_API
    SdfRelationshipSpecHandle GetRelationshipAtPath(const SdfPath &path);
 
 
    SDF_API
    bool PermissionToEdit() const;
 
    SDF_API
    bool PermissionToSave() const;
 
    SDF_API
    void SetPermissionToEdit(bool allow);
 
    SDF_API
    void SetPermissionToSave(bool allow);
 
 
    SDF_API
    SdfNamespaceEditDetail::Result
    CanApply(const SdfBatchNamespaceEdit&,
             SdfNamespaceEditDetailVector* details = NULL) const;
 
    SDF_API
    bool Apply(const SdfBatchNamespaceEdit&);
 
 
    SDF_API
    SdfLayerStateDelegateBasePtr GetStateDelegate() const;
 
    SDF_API
    void SetStateDelegate(const SdfLayerStateDelegateBaseRefPtr& delegate);
 
    SDF_API
    bool IsDirty() const;
 
 
    SDF_API
    std::set<double> ListAllTimeSamples() const;
    
    SDF_API
    std::set<double> 
    ListTimeSamplesForPath(const SdfPath& path) const;
 
    SDF_API
    bool GetBracketingTimeSamples(double time, double* tLower, double* tUpper);
 
    SDF_API
    size_t GetNumTimeSamplesForPath(const SdfPath& path) const;
 
    SDF_API
    bool GetBracketingTimeSamplesForPath(const SdfPath& path, 
                                         double time,
                                         double* tLower, double* tUpper) const;
 
    SDF_API
    bool GetPreviousTimeSampleForPath(const SdfPath& path, double time,
                                      double* tPrevious) const;
 
    SDF_API
    bool QueryTimeSample(const SdfPath& path, double time, 
                         VtValue *value=NULL) const;
 
    SDF_API
    bool QueryTimeSample(const SdfPath& path, double time, 
                         SdfAbstractDataValue *value) const;
 
    template <class T>
    bool QueryTimeSample(const SdfPath& path, double time, 
                         T* data) const
    {
        if (!data) {
            return QueryTimeSample(path, time);
        }
 
        SdfAbstractDataTypedValue<T> outValue(data);
        const bool hasValue = QueryTimeSample(
            path, time, static_cast<SdfAbstractDataValue *>(&outValue));
 
        if (std::is_same<T, SdfValueBlock>::value) {
            return hasValue && outValue.isValueBlock;
        }
 
        return hasValue && (!outValue.isValueBlock);
    }
 
    SDF_API
    void SetTimeSample(const SdfPath& path, double time, 
                       const VtValue & value);
 
    SDF_API
    void SetTimeSample(const SdfPath& path, double time, 
                       const SdfAbstractDataConstValue& value);
 
    template <class T>
    void SetTimeSample(const SdfPath& path, double time, 
                       const T& value)
    {
        const SdfAbstractDataConstTypedValue<T> inValue(&value);
        const SdfAbstractDataConstValue& untypedInValue = inValue;
        return SetTimeSample(path, time, untypedInValue);
    }
 
    SDF_API
    void EraseTimeSample(const SdfPath& path, double time);
 
 
    // Debugging
    // @{
 
    SDF_API
    static void DumpLayerInfo();
 
    // Write this layer's SdfData to a file in a simple generic format.
    SDF_API
    bool WriteDataFile(const std::string &filename);
 
    // @}
 
    SDF_API
    SdfChangeList CreateDiff(
        const SdfLayerHandle& layer,
        bool processPropertyFields = true) const;
 
protected:
    // Private constructor -- use New(), FindOrCreate(), etc.
    // Precondition: _layerRegistryMutex must be locked.
    SdfLayer(const SdfFileFormatConstPtr& fileFormat,
             const std::string &identifier,
             const std::string &realPath = std::string(),
             const ArAssetInfo& assetInfo = ArAssetInfo(),
             const FileFormatArguments &args = FileFormatArguments(),
             bool validateAuthoring = false);
 
private:
    // Create a new layer.
    // Precondition: _layerRegistryMutex must be locked.
    static SdfLayerRefPtr _CreateNew(
        SdfFileFormatConstPtr fileFormat,
        const std::string& identifier,
        const FileFormatArguments& args,
        bool saveLayer = true);
 
    static SdfLayerRefPtr _CreateNewWithFormat(
        const SdfFileFormatConstPtr &fileFormat,
        const std::string& identifier,
        const std::string& realPath,
        const ArAssetInfo& assetInfo = ArAssetInfo(),
        const FileFormatArguments& args = FileFormatArguments());
 
    static SdfLayerRefPtr _CreateAnonymousWithFormat(
        const SdfFileFormatConstPtr &fileFormat,
        const std::string& tag,
        const FileFormatArguments& args);
 
    // Finish initializing this layer (which may have succeeded or not)
    // and publish the results to other threads by unlocking the mutex.
    // Sets _initializationWasSuccessful.
    void _FinishInitialization(bool success);
 
    // Layers retrieved from the layer registry may still be in the
    // process of having their contents initialized.  Other threads
    // retrieving layers from the registry must wait until initialization
    // is complete, using this method.
    // Returns _initializationWasSuccessful.
    //
    // Callers *must* be holding an SdfLayerRefPtr to this layer to
    // ensure that it is not deleted out from under them, in
    // case initialization fails.  (This method cannot acquire the
    // reference itself internally without being susceptible to a race.)
    bool _WaitForInitializationAndCheckIfSuccessful();
 
    // Returns whether or not this layer should post change 
    // notification.  This simply returns (!_GetIsLoading())
    bool _ShouldNotify() const;
 
    // This function keeps track of the last state of IsDirty() before
    // updating it. It returns false if the last saved dirty state is the
    // same than the current state. It returns true if the state differs and
    // will update the 'last dirty state' to the current state. So, after
    // returning true, it would return false for subsequent calls until the
    // IsDirty() state would change again...
    bool _UpdateLastDirtinessState() const;
 
    // Returns a handle to the spec at the given path if it exists and matches
    // type T.
    template <class T>
    SdfHandle<T> _GetSpecAtPath(const SdfPath& path);
 
    // Returns true if a spec can be retrieved at the given path, false
    // otherwise. This function will return the canonicalized path to the
    // spec as well as the spec type.
    bool _CanGetSpecAtPath(const SdfPath& path, 
                           SdfPath* canonicalPath, SdfSpecType* specType) const;
 
    void _InitializeFromIdentifier(
        const std::string &identifier,
        const std::string &realPath = std::string(),
        const std::string &fileVersion = std::string(),
        const ArAssetInfo& assetInfo = ArAssetInfo());
 
    // Helper for computing the necessary information to lookup a layer
    // in the registry or open the layer.
    struct _FindOrOpenLayerInfo;
    static bool _ComputeInfoToFindOrOpenLayer(
        const std::string& identifier,
        const SdfLayer::FileFormatArguments& args,
        _FindOrOpenLayerInfo* info,
        bool computeAssetInfo = false);
 
    // Open a layer, adding an entry to the registry and releasing
    // the registry lock.
    // Precondition: _layerRegistryMutex must be locked.
    template <class Lock>
    static SdfLayerRefPtr _OpenLayerAndUnlockRegistry(
        Lock &lock,
        const _FindOrOpenLayerInfo& info,
        bool metadataOnly);
 
    // Helper function for finding a layer with \p identifier and \p args.
    // \p lock must be unlocked initially and will be locked by this
    // function when needed. See docs for \p retryAsWriter argument on
    // _TryToFindLayer for details on the final state of the lock when
    // this function returns.
    template <class ScopedLock>
    static SdfLayerRefPtr
    _Find(const std::string &identifier,
          const FileFormatArguments &args,
          ScopedLock &lock, bool retryAsWriter);
 
    // Helper function to try to find the layer with \p identifier and
    // pre-resolved path \p resolvedPath in the registry.  Caller must hold
    // registry \p lock for reading.  If \p retryAsWriter is false, lock is
    // released upon return.  Otherwise the lock is released upon return if a
    // layer is found successfully.  If no layer is found then the lock is
    // upgraded to a writer lock upon return.  Note that this upgrade may not be
    // atomic, but this function ensures that if upon return there does not
    // exist a matching layer in the registry.
    template <class ScopedLock>
    static SdfLayerRefPtr
    _TryToFindLayer(const std::string &identifier,
                    const ArResolvedPath &resolvedPath,
                    ScopedLock &lock, bool retryAsWriter);
 
    bool _IsInert(const SdfPath &path, bool ignoreChildren, 
                  bool requiredFieldOnlyPropertiesAreInert = false) const;
 
    bool _IsInertSubtree(const SdfPath &path) const;
 
    void _RemoveIfInert(const SdfSpec& spec);
 
    bool _RemoveInertDFS(SdfPrimSpecHandle prim);
 
    void _RemoveInertToRootmost(SdfPrimSpecHandle prim);
 
    bool _ValidateAuthoring() const { return _validateAuthoring; }
 
    std::string _GetMutedPath() const;
 
    // If old and new asset path is given, rename all external prim
    // composition dependency referring to the old path.
    void _UpdatePrimCompositionDependencyPaths(
        const SdfPrimSpecHandle &parent,
        const std::string &oldLayerPath,
        const std::string &newLayerPath);
 
    // Set the clean state to the current state.
    void _MarkCurrentStateAsClean() const;
 
    // Return the field definition for \p fieldName if \p fieldName is a
    // required field for the spec type identified by \p path.
    inline SdfSchema::FieldDefinition const *
    _GetRequiredFieldDef(const SdfPath &path,
                         const TfToken &fieldName,
                         SdfSpecType specType = SdfSpecTypeUnknown) const;
 
    // Return the field definition for \p fieldName if \p fieldName is a
    // required field for \p specType subject to \p schema.
    static inline SdfSchema::FieldDefinition const *
    _GetRequiredFieldDef(const SdfSchemaBase &schema,
                         const TfToken &fieldName,
                         SdfSpecType specType);
 
    // Helper to list all fields on \p data at \p path subject to \p schema.
    static std::vector<TfToken>
    _ListFields(SdfSchemaBase const &schema,
                SdfAbstractData const &data, const SdfPath& path);
 
    // Helper for HasField for \p path in \p data subject to \p schema.
    static inline bool
    _HasField(const SdfSchemaBase &schema,
              const SdfAbstractData &data,
              const SdfPath& path,
              const TfToken& fieldName,
              VtValue *value);
 
    // Helper to get a field value for \p path in \p data subject to \p schema.
    static inline VtValue
    _GetField(const SdfSchemaBase &schema,
              const SdfAbstractData &data,
              const SdfPath& path,
              const TfToken& fieldName);
    
    // Set a value.
    template <class T>
    void _SetValue(const TfToken& key, T value);
 
    // Get a value.
    template <class T>
    T _GetValue(const TfToken& key) const;
 
    enum _ReloadResult { _ReloadFailed, _ReloadSucceeded, _ReloadSkipped };
    _ReloadResult _Reload(bool force);
 
    // Reads contents of asset specified by \p identifier with resolved
    // path \p resolvedPath into this layer.
    bool _Read(const std::string& identifier, 
               const ArResolvedPath& resolvedPath, 
               bool metadataOnly);
    
    // Saves this layer if it is dirty or the layer doesn't already exist
    // on disk. If \p force is true, the layer will be written out
    // regardless of those conditions.
    bool _Save(bool force) const;
 
    // A helper method used by Save and Export.
    // This method allows Save to specify the existing file format and Export
    // to use the format provided by the file extension in newFileName. If no
    // file format can be discovered from the file name, the existing file
    // format associated with the layer will be used in both cases. This allows
    // users to export and save to any file name, regardless of extension.
    bool _WriteToFile(const std::string& newFileName, 
                      const std::string& comment, 
                      SdfFileFormatConstPtr fileFormat,
                      const FileFormatArguments& args) const;
 
    // Swap contents of _data and data. This operation does not register
    // inverses or emit change notification.
    void _SwapData(SdfAbstractDataRefPtr &data);
 
    // Set _data to \p newData and send coarse DidReplaceLayerContent
    // invalidation notice.
    void _AdoptData(const SdfAbstractDataRefPtr &newData);
 
    // Helper function which will process incoming data to this layer in a
    // generic way. 
    // If \p processPropertyFields is false, this method will not
    // consider property spec fields. In some cases, this can avoid expensive
    // operations which would pull large amounts of data.
    template<typename DeleteSpecFunc, typename CreateSpecFunc, 
            typename GetFieldValuesFunc, typename SetFieldFunc, typename ErrorFunc>
    void _ProcessIncomingData(const SdfAbstractDataPtr &newData,
                              const SdfSchemaBase *newDataSchema,
                              bool processPropertyFields,
                              const DeleteSpecFunc &deleteSpecFunc,
                              const CreateSpecFunc &createSpecFunc,
                              const GetFieldValuesFunc &getFieldValuesFunc,
                              const SetFieldFunc &setFieldFunc,
                              const ErrorFunc &errorFunc) const;
 
    // Set _data to match data, calling other primitive setter methods to
    // provide fine-grained inverses and notification.  If \p data might adhere
    // to a different schema than this layer's, pass a pointer to it as \p
    // newDataSchema.  In this case, check to see if fields from \p data are
    // known to this layer's schema, and if not, omit them and issue a TfError
    // with SdfAuthoringErrorUnrecognizedFields, but continue to set all other
    // known fields.
    void _SetData(const SdfAbstractDataPtr &newData,
                  const SdfSchemaBase *newDataSchema=nullptr);
 
    // Returns const handle to _data.
    SdfAbstractDataConstPtr _GetData() const;
 
    // Returns a new SdfAbstractData object for this layer.
    SdfAbstractDataRefPtr _CreateData() const;
 
    // Inverse primitive for setting a single field. The previous value for the
    // field may be given via \p oldValue. If \p oldValue is non-nullptr, the
    // VtValue it points to will be moved-from after the function completes. If
    // \p oldValue is nullptr, the old field value will be retrieved
    // automatically.
    template <class T>
    void _PrimSetField(const SdfPath& path, 
                       const TfToken& fieldName,
                       const T& value,
                       VtValue *oldValue = nullptr,
                       bool useDelegate = true);
 
    // Inverse primitive for setting a single key in a dict-valued field.  The
    // previous dictionary value for the field (*not* the individual entry) may
    // be supplied via \p oldValue. If \p oldValue is non-nullptr, the VtValue
    // it points to will be moved-from after the function completes. If \p
    // oldValue is nullptr, the old field value will be retrieved automatically.
    template <class T>
    void _PrimSetFieldDictValueByKey(const SdfPath& path,
                                     const TfToken& fieldName,
                                     const TfToken& keyPath,
                                     const T& value,
                                     VtValue *oldValue = nullptr,
                                     bool useDelegate = true);
 
    // Primitive for appending a child to the list of children.
    template <class T>
    void _PrimPushChild(const SdfPath& parentPath,
                        const TfToken& fieldName,
                        const T& value,
                        bool useDelegate = true);
    template <class T>
    void _PrimPopChild(const SdfPath& parentPath,
                       const TfToken& fieldName,
                       bool useDelegate = true);
 
    // Move all the fields at all paths at or below \a oldPath to be
    // at a corresponding location at or below \a newPath. This does
    // not update the children fields of the parents of these paths.
    bool _MoveSpec(const SdfPath &oldPath, const SdfPath &newPath);
 
    // Inverse primitive for moving a spec.
    void _PrimMoveSpec(const SdfPath &oldPath, const SdfPath &newPath,
                       bool useDelegate = true);
 
    // Create a new spec of type \p specType at \p path.
    // Returns true if spec was successfully created, false otherwise.
    bool _CreateSpec(const SdfPath& path, SdfSpecType specType, bool inert);
 
    // Delete all the fields at or below the specified path. This does
    // not update the children field of the parent of \a path.
    bool _DeleteSpec(const SdfPath &path);
 
    // Inverse primitive for deleting a spec.
    void _PrimCreateSpec(const SdfPath &path, SdfSpecType specType, bool inert,
                         bool useDelegate = true);
 
    // Inverse primitive for deleting a spec.
    void _PrimDeleteSpec(const SdfPath &path, bool inert, 
                         bool useDelegate = true);
 
    // Inverse primitive for setting time samples.
    template <class T>
    void _PrimSetTimeSample(const SdfPath& path, double time,
                            const T& value,
                            bool useDelegate = true);
 
    // Helper method for Traverse. Visits the children of \a path using the
    // specified \a ChildPolicy.
    template <typename ChildPolicy>
    void _TraverseChildren(const SdfPath &path, const TraversalFunction &func);
 
private:
    SdfLayerHandle _self;
 
    // File format and arguments for this layer.
    SdfFileFormatConstPtr _fileFormat;
    FileFormatArguments _fileFormatArgs;
 
    // Cached reference to the _fileFormat's schema -- we need access to this to
    // be as fast as possible since we look at it on every SetField(), for
    // example.
    const SdfSchemaBase &_schema;
 
    // Registry of Sdf Identities
    mutable Sdf_IdentityRegistry _idRegistry;
 
    // The underlying SdfData which stores all the data in the layer.
    SdfAbstractDataRefPtr _data;
 
    // The state delegate for this layer.
    SdfLayerStateDelegateBaseRefPtr _stateDelegate;
 
    // Dispatcher used in layer initialization, letting waiters participate in
    // loading instead of just busy-waiting.
    WorkDispatcher _initDispatcher;
    
    // Atomic variable protecting layer initialization -- the interval between
    // adding a layer to the layer registry and finishing the process of
    // initializing its contents, at which point we can truly publish the layer
    // for consumption by concurrent threads. We add the layer to the registry
    // before initialization completes so that other threads can discover and
    // wait for it to finish initializing.
    std::atomic<bool> _initializationComplete;
 
    // This is an optional<bool> that is only set once initialization
    // is complete, before _initializationComplete is set.
    std::optional<bool> _initializationWasSuccessful;
 
    // remembers the last 'IsDirty' state.
    mutable bool _lastDirtyState;
 
    // Asset information for this layer.
    std::unique_ptr<Sdf_AssetInfo> _assetInfo;
 
    // Modification timestamp of the backing file asset when last read.
    mutable VtValue _assetModificationTime;
 
    // All external asset dependencies, with their modification timestamps, of
    // the layer when last read.
    mutable VtDictionary _externalAssetModificationTimes;
 
    // Mutable revision number for cache invalidation.
    mutable size_t _mutedLayersRevisionCache;
 
    // Cache of whether or not this layer is muted.  Only valid if
    // _mutedLayersRevisionCache is up-to-date with the global revision number.
    mutable bool _isMutedCache;
 
    // Layer permission bits.
    bool _permissionToEdit;
    bool _permissionToSave;
 
    // Whether layer edits are validated.
    bool _validateAuthoring;
 
    // Layer hints as of the most recent save operation.
    mutable SdfLayerHints _hints;
 
    // Allow access to _ValidateAuthoring() and _IsInert().
    friend class SdfSpec;
    friend class SdfPropertySpec;
    friend class SdfAttributeSpec;
 
    friend class Sdf_ChangeManager;
 
    // Allow access to _CreateSpec and _DeleteSpec and _MoveSpec
    template <class ChildPolicy> friend class Sdf_ChildrenUtils;
 
    // Give the file format access to our data.  Limit breaking encapsulation
    // to the base SdFileFormat class so we don't have to friend every
    // implementation here.
    friend class SdfFileFormat;
 
    // Give layer state delegates access to our data as well as to
    // the various _Prim functions.
    friend class SdfLayerStateDelegateBase;
};
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif // PXR_USD_SDF_LAYER_H