stageData.h

Go to the documentation of this file.

//
// Copyright 2026 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_EXEC_ESF_USD_STAGE_DATA_H
#define PXR_EXEC_ESF_USD_STAGE_DATA_H


#include "pxr/pxr.h"

#include "pxr/exec/esfUsd/api.h"

#include "pxr/base/tf/declarePtrs.h"
#include "pxr/base/tf/hash.h"
#include "pxr/usd/sdf/path.h"
#include "pxr/usd/usd/notice.h"

#ifdef TBB_PREVIEW_CONCURRENT_ORDERED_CONTAINERS
#include <tbb/concurrent_map.h>
#else
#define TBB_PREVIEW_CONCURRENT_ORDERED_CONTAINERS 1
#include <tbb/concurrent_map.h>
#undef TBB_PREVIEW_CONCURRENT_ORDERED_CONTAINERS
#endif

#include <tbb/concurrent_unordered_map.h>
#include <tbb/concurrent_unordered_set.h>
#include <tbb/concurrent_vector.h>

#include <memory>
#include <mutex>
#include <vector>

PXR_NAMESPACE_OPEN_SCOPE

class UsdAttribute;
class UsdPrim;

TF_DECLARE_WEAK_PTRS(UsdStage);

class EsfUsdStageData
{
    EsfUsdStageData(const UsdStageConstPtr &stage);

public:

    using ChangedPathSet = tbb::concurrent_unordered_set<SdfPath, TfHash>;

    class ESFUSD_API_TYPE ListenerBase {
    public:
        ESFUSD_API
        virtual ~ListenerBase();

    private:
        friend EsfUsdStageData;

        virtual void _DidObjectsChanged(
            const UsdNotice::ObjectsChanged &objectsChanged,
            const ChangedPathSet &changedTargetPaths) const = 0;
    };
    

    ESFUSD_API
    ~EsfUsdStageData();

    ESFUSD_API
    static std::shared_ptr<EsfUsdStageData> RegisterStage(
        const UsdStageConstPtr &stage,
        const ListenerBase *listener);

    ESFUSD_API
    void Unregister(
        const ListenerBase *listener);

    ESFUSD_API
    static EsfUsdStageData &GetStageData(
        const UsdStageConstPtr &stage);

    ESFUSD_API
    static const SdfPathVector &GetOutgoingConnections(
        const UsdStageConstPtr &stage,
        const SdfPath &attrPath);

    ESFUSD_API
    static SdfPathVector GetIncomingConnections(
        const UsdStageConstPtr &stage,
        const SdfPath &targetPath);

private:
    const UsdStageConstPtr &_GetStage() const { return _stage; }

    const SdfPathVector &_GetOutgoingConnections(
        const SdfPath &targetPath);

    SdfPathVector _GetIncomingConnections(
        const SdfPath &targetPath);

    void _PopulateConnectionTables();

    // Define a type and a corresponding transparent comparator so that we can
    // use lower_bound to find the end of a map range with keys that are paths
    // with a given prefix.

    struct _PathPrefix
    {
        SdfPath prefix;
    };

    struct _PathRangeLessThan
    {
        using is_transparent = void;

        bool operator()(const SdfPath &lhs, const SdfPath &rhs) const {
            return lhs < rhs;
        }

        bool operator()(const SdfPath &lhs, const _PathPrefix& rhs) const {
            return lhs < rhs.prefix || lhs.HasPrefix(rhs.prefix);
        }
    };

    // A concurrent map from owning attribute paths to target object paths.
    using _OutgoingPathTable =
        tbb::concurrent_map<SdfPath, SdfPathVector, _PathRangeLessThan>;

    // A concurent map from target object paths to owning attribute paths.
    using _IncomingPathTable =
        tbb::concurrent_unordered_map<
            SdfPath, tbb::concurrent_vector<SdfPath>, TfHash>;

    // Gets the new (i.e., current) connections for the given attribute and
    // computes the added and removed target paths, relative to what was
    // previously stored in the outgoing connection paths table.
    //
    void _GetChangedConnectionTargets(
        const SdfPath &attrPath,
        const UsdAttribute &attribute,
        SdfPathVector *newConnections,
        SdfPathVector *addedTargetPaths,
        SdfPathVector *removedTargetPaths) const;

    // Updates attribute connection caches for connections owned by the
    // attribute at \p attrPath.
    //
    // Populates \p incomingConnectionsChanged with the paths of objects whose
    // incoming connection paths have changed.
    //
    void _UpdateForChangedAttributeConnections(
        const SdfPath &attrPath,
        ChangedPathSet *incomingConnectionsChanged);

    // Updates attribute connection caches for connections owned by attribute
    // at or under \p resyncedPath.
    //
    void _UpdateForResync(
        const SdfPath &resyncedPath,
        ChangedPathSet *incomingConnectionsChanged);

    // Updates outgoing and incoming connection tables for any changes to the
    // given prim.
    //
    // New incoming connections are added immediately; new outgoing connections
    // and removed incoming connections are queued up for deferred processing,
    // to allow this method to be called in parallel.
    //
    void _UpdateForChangedPrim(
        const UsdPrim &prim,
        _IncomingPathTable *incomingToRemove,
        ChangedPathSet *incomingConnectionsChanged);

    // Find entries in the outgoing connections map for attributes on the
    // resynced prim and its descendants that no longer exist in the scene,
    // populating \p ownerAttrsToRemove and \p incomingToRemove.
    //
    void _UpdateForRemovedAttributes(
        const SdfPath &resyncedPath,
        _IncomingPathTable *incomingToRemove,
        tbb::concurrent_vector<SdfPath> *ownerAttrsToRemove) const;

    // Removes the entries indicated by \p incomingToRemove from _incoming.
    void _RemoveIncomingTableEntries(
        const _IncomingPathTable &incomingToRemove);

    // Notifies all listeners of changes.
    void _Notify(
        const UsdNotice::ObjectsChanged &objectsChanged,
        const ChangedPathSet &changedTargetPaths) const;

private:
    const UsdStageConstPtr _stage;

    // Used to listen for change notification from the stage.
    class _NoticeListener;
    const std::unique_ptr<_NoticeListener> _noticeListener;

    // Registered listeners, used to communicate change notfication to clients.
    std::vector<const ListenerBase *> _listeners;
    mutable std::mutex _listenersMutex;

    _OutgoingPathTable _outgoing;

    _IncomingPathTable _incoming;
};

PXR_NAMESPACE_CLOSE_SCOPE

#endif