layer.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_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 <boost/optional.hpp>

#include <atomic>
#include <functional>
#include <memory>
#include <set>
#include <string>
#include <vector>

PXR_NAMESPACE_OPEN_SCOPE

TF_DECLARE_WEAK_PTRS(SdfFileFormat);
TF_DECLARE_WEAK_AND_REF_PTRS(SdfLayerStateDelegateBase);

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
    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
    void SetDefaultPrim(const TfToken &name);

    SDF_API
    void ClearDefaultPrim();

    SDF_API
    bool HasDefaultPrim();

    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();


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

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

    // @}

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

    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 menv 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 std::string &resolvedPath,
                    ScopedLock &lock, bool retryAsWriter);

    bool _IsInert(const SdfPath &path, bool ignoreChildren, 
                  bool requiredFieldOnlyPropertiesAreInert = false) const;

    bool _IsInertSubtree(const SdfPath &path,
                         std::vector<SdfPath>* inertSpecs = nullptr);

    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 std::string& 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 = TfNullPtr,
                      const FileFormatArguments& args = FileFormatArguments())
                      const;

    // Swap contents of _data and data. This operation does not register
    // inverses or emit change notification.
    void _SwapData(SdfAbstractDataRefPtr &data);

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

    // Inverse primitive for setting a single field.
    template <class T>
    void _PrimSetField(const SdfPath& path, 
                       const TfToken& fieldName,
                       const T& value,
                       const VtValue *oldValue = NULL,
                       bool useDelegate = true);

    // Inverse primitive for setting a single key in a dict-valued field.
    template <class T>
    void _PrimSetFieldDictValueByKey(const SdfPath& path,
                                     const TfToken& fieldName,
                                     const TfToken& keyPath,
                                     const T& value,
                                     const VtValue *oldValue = NULL,
                                     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.
    boost::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