changes.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_PCP_CHANGES_H
#define PXR_USD_PCP_CHANGES_H


#include "pxr/pxr.h"
#include "pxr/usd/pcp/api.h"
#include "pxr/usd/pcp/dependency.h"
#include "pxr/usd/pcp/errors.h"
#include "pxr/usd/pcp/layerStackIdentifier.h"
#include "pxr/usd/sdf/changeList.h"
#include "pxr/usd/sdf/declareHandles.h"
#include "pxr/usd/sdf/path.h"
#include "pxr/usd/sdf/types.h"
#include "pxr/base/tf/declarePtrs.h"

#include <map>
#include <set>
#include <unordered_set>

PXR_NAMESPACE_OPEN_SCOPE

SDF_DECLARE_HANDLES(SdfLayer);
TF_DECLARE_WEAK_AND_REF_PTRS(PcpLayerStack);

class PcpCache;
class PcpSite;

class PcpLayerStackChanges {
public:
    bool didChangeLayers;

    bool didChangeLayerOffsets;

    bool didChangeRelocates;

    bool didChangeExpressionVariables;

    bool didChangeSignificantly;

    SdfRelocatesMap newRelocatesTargetToSource;
    SdfRelocatesMap newRelocatesSourceToTarget;
    SdfRelocatesMap newIncrementalRelocatesSourceToTarget;
    SdfRelocatesMap newIncrementalRelocatesTargetToSource;
    SdfPathVector newRelocatesPrimPaths;
    PcpErrorVector newRelocatesErrors;

    SdfPathSet pathsAffectedByRelocationChanges;

    VtDictionary newExpressionVariables;

    PcpLayerStackChanges()
        : didChangeLayers(false)
        , didChangeLayerOffsets(false)
        , didChangeRelocates(false)
        , didChangeExpressionVariables(false)
        , didChangeSignificantly(false)
        , _didChangeExpressionVariablesSource(false)
    {}

private:
    friend class PcpChanges;
    friend class PcpLayerStack;

    // Expression variables source has changed.
    bool _didChangeExpressionVariablesSource;

    // New source for expression variables for this layer stack.
    PcpExpressionVariablesSource _newExpressionVariablesSource;
};

class PcpCacheChanges {
public:
    enum TargetType {
        TargetTypeConnection         = 1 << 0,
        TargetTypeRelationshipTarget = 1 << 1
    };

    SdfPathSet didChangeSignificantly;

    SdfPathSet didChangeSpecs;

    SdfPathSet didChangePrims;

    std::map<SdfPath, int, SdfPath::FastLessThan> didChangeTargets;

    std::vector<std::pair<SdfPath, SdfPath>> didChangePath;

    bool didMaybeChangeLayers = false;

    std::unordered_set<SdfLayerHandle, TfHash> layersAffectedByMutingOrRemoval;

    // Holds all the diff changelists that were computed when adding/removing
    // sublayers or muting/unmuting layers.
    SdfLayerChangeListVec layerChangeListVec;

private:
    friend class PcpCache;
    friend class PcpChanges;

    using _ProcessedLayerSublayerPathPairsKey = 
        std::pair<SdfLayerHandle, std::string>;

    using _LayerToLayerStacks = 
        std::unordered_map<SdfLayerHandle, PcpLayerStackPtrVector, TfHash>;

    void _SetLayerStacksUsingLayerOverride(
        const SdfLayerHandle& layer, 
        const PcpLayerStackPtrVector& layerStacks);

    const PcpLayerStackPtrVector&
    _GetLayerStacksUsingLayerOverride(const SdfLayerHandle& layer) const;

    // Set of hashed layer / sublayer path pairs that have been processed in
    // in this round of changes.  These values are checked in order to avoid
    // recursively processing cycles created in layer stacks.
    std::unordered_set<_ProcessedLayerSublayerPathPairsKey, TfHash> 
        _processedLayerSublayerPathPairs;

    // Must rebuild the prim/property stacks at each path due to a change
    // that only affects the internal representation of the stack and
    // not its contents.  Because this causes no externally-observable
    // changes in state, clients do not need to be aware of these changes.
    SdfPathSet _didChangeSpecsInternal;

    // This set serves a similar purpose to _didChangeSpecsInternal above,
    // however, during processing descendants of the specs in this set will also
    // be marked as changed. A performance gain is accomplished by placing the
    // ancestor specs in this set and processing children iteratively when
    // applying changes to the cache.
    SdfPathSet _didChangePrimSpecsAndChildrenInternal;

    // Holds layer stack overrides set for individual layers
    _LayerToLayerStacks _layerToLayerStackOverrides;
};

class PcpLifeboat {
public:
    PcpLifeboat();
    ~PcpLifeboat();

    void Retain(const SdfLayerRefPtr& layer);

    void Retain(const PcpLayerStackRefPtr& layerStack);

    const std::set<PcpLayerStackRefPtr>& GetLayerStacks() const;

    void Swap(PcpLifeboat& other);

private:
    std::set<SdfLayerRefPtr> _layers;
    std::set<PcpLayerStackRefPtr> _layerStacks;
};

class PcpChanges {
public:
    PCP_API PcpChanges();
    PCP_API ~PcpChanges();

    PCP_API 
    void DidChange(const PcpCache* cache,
                   const SdfLayerChangeListVec& changes);

    PCP_API 
    void DidMaybeFixSublayer(const PcpCache* cache,
                             const SdfLayerHandle& layer,
                             const std::string& assetPath);

    PCP_API 
    void DidMaybeFixAsset(const PcpCache* cache,
                          const PcpSite& site,
                          const SdfLayerHandle& srcLayer,
                          const std::string& assetPath);

    PCP_API 
    void _DidMuteLayer(const PcpCache* cache, const std::string& layerId);

    PCP_API 
    void _DidUnmuteLayer(const PcpCache* cache, const std::string& layerId);

    void DidMuteAndUnmuteLayers(const PcpCache* cache, 
                              const std::vector<std::string>& layersToMute,
                              const std::vector<std::string>& layersToUnmute);

    PCP_API 
    void DidChangeSignificantly(const PcpCache* cache, const SdfPath& path);

    enum ChangeSpecsType {
        ChangeSpecsTypeRemoved,
        ChangeSpecsTypeAdded
    };

    PCP_API 
    void DidChangeSpecs(const PcpCache* cache, const SdfPath& path,
                        const SdfLayerHandle& changedLayer,
                        const SdfPath& changedPath, ChangeSpecsType changeType);

    PCP_API 
    void DidChangeSpecStack(const PcpCache* cache, const SdfPath& path);

    PCP_API 
    void DidChangeTargets(const PcpCache* cache, const SdfPath& path,
                          PcpCacheChanges::TargetType targetType);

    PCP_API 
    void DidChangePaths(const PcpCache* cache,
                        const SdfPath& oldPath, const SdfPath& newPath);

    PCP_API
    void DidDestroyCache(const PcpCache* cache);

    PCP_API
    void DidChangeAssetResolver(const PcpCache* cache);

    PCP_API
    void Swap(PcpChanges& other);

    PCP_API
    bool IsEmpty() const;

    typedef std::map<PcpLayerStackPtr, PcpLayerStackChanges> LayerStackChanges;
    typedef std::map<PcpCache*, PcpCacheChanges> CacheChanges;

    PCP_API
    const LayerStackChanges& GetLayerStackChanges() const;

    PCP_API
    const CacheChanges& GetCacheChanges() const;

    PCP_API
    const PcpLifeboat& GetLifeboat() const;

    PCP_API
    void Apply() const;

    PCP_API
    PcpDependencyVector
    FindSiteDependencies(const PcpCache* cache,
                         const SdfLayerHandle& siteLayer,
                         const SdfPath& sitePath,
                         PcpDependencyFlags depMask,
                         bool recurseOnSite,
                         bool recurseOnIndex,
                         bool filterForExistingCachesOnly) const;

    PCP_API
    const PcpLayerStackPtrVector& 
    FindAllLayerStacksUsingLayer(const PcpCache* cache, 
                                 const SdfLayerHandle& layer) const;

private:
    // Internal data types for namespace edits from Sd.
    typedef std::map<SdfPath, SdfPath> _PathEditMap;
    typedef std::map<PcpCache*, _PathEditMap> _RenameChanges;

    // Returns the PcpLayerStackChanges for the given layer stack.
    PcpLayerStackChanges& _GetLayerStackChanges(const PcpLayerStackPtr&);

    // Returns the PcpCacheChanges for the given cache.
    PcpCacheChanges& _GetCacheChanges(const PcpCache* cache);

    // Returns the _PathEditMap for the given cache.
    _PathEditMap& _GetRenameChanges(const PcpCache* cache);


    // Optimize the changes.
    void _Optimize() const;

    // Optimize the changes.
    void _Optimize();

    // Optimize the changes for a given cache.
    void _Optimize(PcpCacheChanges*);

    // Optimize path changes.
    void _OptimizePathChanges(const PcpCache* cache, PcpCacheChanges* changes,
                              const _PathEditMap* pathChanges);

    // Sublayer change type for _DidChangeSublayer.
    enum _SublayerChangeType {
        _SublayerAdded,
        _SublayerRemoved
    };

    // Helper function for loading a sublayer of \p layer at \p sublayerPath
    // for processing changes described by \p sublayerChange.
    SdfLayerRefPtr _LoadSublayerForChange(const PcpCache* cache,
                                          const SdfLayerHandle& layer,
                                          const std::string& sublayerPath,
                                          _SublayerChangeType changeType) const;

    // Helper function for loading a sublayer at \p sublayerPath
    // for processing changes described by \p sublayerChange.
    SdfLayerRefPtr _LoadSublayerForChange(const PcpCache* cache,
                                          const std::string& sublayerPath,
                                          _SublayerChangeType changeType) const;

    // Propagates changes to \p sublayer specified by \p sublayerChange to 
    // the dependents of that sublayer.  This includes all layer stacks
    // that include the sublayer.
    void _DidChangeSublayerAndLayerStacks(const PcpCache* cache,
                                          const PcpLayerStackPtrVector& stacks,
                                          const std::string& sublayerPath,
                                          const SdfLayerHandle& sublayer,
                                          _SublayerChangeType sublayerChange,
                                          std::string* debugSummary);

    // Propagates changes to \p sublayer specified by \p sublayerChange to 
    // the dependents of that sublayer.
    void _DidChangeSublayer(const PcpCache* cache,
                            const PcpLayerStackPtrVector& layerStacks,
                            const std::string& sublayerPath,
                            const SdfLayerHandle& sublayer,
                            _SublayerChangeType sublayerChange,
                            std::string* debugSummary,
                            bool *significant);

    // Propagates changes due to the addition/removal of the sublayer
    // at the given \p sublayerPath to/from the parent \p layer.
    void _DidAddOrRemoveSublayer(const PcpCache* cache,
                                 const PcpLayerStackPtrVector& layerStacks,
                                 const SdfLayerHandle& layer,
                                 const std::string& sublayerPath,
                                 _SublayerChangeType sublayerChange,
                                 std::string* debugSummary,
                                 std::vector<bool> *significant);

    // Mark the layer stack as having changed.
    void _DidChangeLayerStack(
        const PcpCache* cache,
        const PcpLayerStackPtr& layerStack,
        bool requiresLayerStackChange,
        bool requiresLayerStackOffsetsChange,
        bool requiresSignificantChange);

    // Mark the layer stack's relocations as having changed.
    // Recompute the new relocations, storing the result in the Changes,
    // so that change-processing can determine which other caches it
    // needs to invalidate.
    void _DidChangeLayerStackRelocations(
        const PcpCache* cache,
        const PcpLayerStackPtr& layerStack,
        std::string* debugSummary);

    // Register changes to any prim indexes in \p caches that are affected
    // by a change to a layer's resolved path used by \p layerStack.
    void _DidChangeLayerStackResolvedPath(
        const PcpCache* cache,
        const PcpLayerStackPtr& layerStack,
        bool requiresLayerStackChange,
        std::string* debugSummary);

    // Register changes to layer stacks and prim indexes in \p cache that are
    // affected by a change to a layer's expression variables used by
    // \p layerStack.
    void _DidChangeLayerStackExpressionVariables(
        const PcpCache* cache,
        const PcpLayerStackPtr& layerStack,
        std::string* debugSummary);

    // The spec stack for the prim or property index at \p path must be
    // recomputed due to a change that affects only the internal representation
    // of the stack and not its contents.
    void _DidChangeSpecStackInternal(
        const PcpCache* cache, const SdfPath& path);

    void _DidChangeSpecStackAndChildrenInternal(
        const PcpCache* cache, const SdfPath& path);

    // This method is used when processing layer operations.  It ensures that
    // affected layer stacks and their dependent spec stacks are marked as
    // changed.
    void _ProcessLayerStackAndDependencyChanges(
        const PcpCache* cache,
        const PcpLayerStackPtrVector& layerStacks);

    // When muting or unmuting a layer that is being referenced or payloaded,
    // we need to ensure that all the relevant sites are recomposed.  This
    // function searches site dependencies of the provided layer stacks and
    // marks those that are introduced via reference or payload arcs as
    // significantly changed.
    void _MarkReferencingSitesAsSignificantlyChanged(
        const PcpCache* cache,
        const PcpLayerStackPtrVector& layerStacks);

private:
    LayerStackChanges _layerStackChanges;
    CacheChanges _cacheChanges;
    _RenameChanges _renameChanges;
    mutable PcpLifeboat _lifeboat;
};

PXR_NAMESPACE_CLOSE_SCOPE

#endif // PXR_USD_PCP_CHANGES_H