expressionEvaluatingSceneIndexBase.h

//
// Copyright 2026 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_IMAGING_HDSI_EXPRESSION_EVALUATING_SCENE_INDEX_BASE_H
#define PXR_IMAGING_HDSI_EXPRESSION_EVALUATING_SCENE_INDEX_BASE_H
 
#include "pxr/pxr.h"
#include "pxr/imaging/hdsi/api.h"
 
#include "pxr/imaging/hd/instancingAwareCollectionExpressionEvaluator.h"
#include "pxr/imaging/hd/filteringSceneIndex.h"
#include "pxr/imaging/hd/sceneIndexObserver.h"
 
#include "pxr/usd/sdf/path.h"
#include "pxr/usd/sdf/pathExpression.h"
 
PXR_NAMESPACE_OPEN_SCOPE
 
class HdInstanceProxyViewSceneIndex;
 
TF_DECLARE_REF_PTRS(HdsiExpressionEvaluatingSceneIndexBase);
TF_DECLARE_REF_PTRS(HdInstanceProxyViewSceneIndex);
 
// Alias that's also defined in hd/collectionPredicateLibrary.h
using HdCollectionPredicateLibrary =
    SdfPredicateLibrary<const HdSceneIndexPrim &>;
 
class HdsiExpressionEvaluatingSceneIndexBase
    : public HdFilteringSceneIndexBase, HdEncapsulatingSceneIndexBase
{
public:
    HDSI_API
    std::vector<HdSceneIndexBaseRefPtr> GetInputScenes() const final;
 
    HDSI_API
    std::vector<HdSceneIndexBaseRefPtr> GetEncapsulatedScenes() const override;
 
    HDSI_API
    HdSceneIndexPrim GetPrim(const SdfPath &primPath) const final;
 
    HDSI_API
    SdfPathVector GetChildPrimPaths(const SdfPath &primPath) const final;
 
protected:
    HDSI_API
    explicit HdsiExpressionEvaluatingSceneIndexBase(
        const HdSceneIndexBaseRefPtr &inputSceneIndex,
        const HdCollectionPredicateLibrary &predicateLibrary);
 
    // -----------------------------------------------------------------------
    // Query hooks
 
    HDSI_API
    virtual void _ModifyPrim(
        const SdfPath &primPath, HdSceneIndexPrim *prim) const;
 
    HDSI_API
    virtual void _FilterChildPrimPaths(
        const SdfPath &primPath, SdfPathVector *children) const;
 
    HDSI_API
    virtual bool _IsPruned(const SdfPath &primPath) const;
 
    // -----------------------------------------------------------------------
    // Notice hooks (pure virtual)
    //
    // Each hook provides the input entries and returns a resullt that bundles
    // optional added, removed, and dirtied entries, and indicates whether to
    // forward the input notices as-is to downstream observers.
    //
    // The base class implementations of the non-virtual notice handlers call
    // these hooks and forwards the resulting notices in the following order:
    //     Added, Removed, Dirtied.
    //
    // The _IsObserved() check runs after the hook so derived classes can
    // track state unconditionally.
 
public:
    using OptionalAddedEntries =
        std::optional<HdSceneIndexObserver::AddedPrimEntries>;
    using OptionalRemovedEntries =
        std::optional<HdSceneIndexObserver::RemovedPrimEntries>;
    using OptionalDirtiedEntries =
        std::optional<HdSceneIndexObserver::DirtiedPrimEntries>;
 
    struct NoticeProcessingResult {
        static NoticeProcessingResult ForwardInputNotices() {
            return NoticeProcessingResult(true);
        }
 
        static NoticeProcessingResult Empty() {
            return NoticeProcessingResult(false);
        }
 
        explicit NoticeProcessingResult(bool forwardInputNotices)
            : forwardInputNotices(forwardInputNotices) {}
 
        NoticeProcessingResult& SetAddedEntries(
            const HdSceneIndexObserver::AddedPrimEntries &entries) {
            addedEntries = entries;
            return *this;
        }
 
        NoticeProcessingResult& SetRemovedEntries(
            const HdSceneIndexObserver::RemovedPrimEntries &entries) {
            removedEntries = entries;
            return *this;
        }
 
        NoticeProcessingResult& SetDirtiedEntries(
            const HdSceneIndexObserver::DirtiedPrimEntries &entries) {
            dirtiedEntries = entries;
            return *this;
        }
 
        bool forwardInputNotices;
        OptionalAddedEntries   addedEntries;
        OptionalRemovedEntries removedEntries;
        OptionalDirtiedEntries dirtiedEntries;
    };
 
protected:
    virtual NoticeProcessingResult _PrimsAdded(
        const HdSceneIndexBase &sender,
        const HdSceneIndexObserver::AddedPrimEntries &inputEntries) = 0;
 
    virtual NoticeProcessingResult _PrimsRemoved(
        const HdSceneIndexBase &sender,
        const HdSceneIndexObserver::RemovedPrimEntries &inputEntries) = 0;
 
    virtual NoticeProcessingResult _PrimsDirtied(
        const HdSceneIndexBase &sender,
        const HdSceneIndexObserver::DirtiedPrimEntries &inputEntries) = 0;
 
    // Default implementation converts the renamed entries to removed and added
    // entries and calls _PrimsRemoved and _PrimsAdded. Derived classes can
    // override this to handle renamed entries directly.
    virtual NoticeProcessingResult _PrimsRenamed(
        const HdSceneIndexBase &sender,
        const HdSceneIndexObserver::RenamedPrimEntries &inputEntries);
 
    // -----------------------------------------------------------------------
    // Utilities
 
    HDSI_API
    HdInstancingAwareCollectionExpressionEvaluator _MakeEvaluator(
        const SdfPathExpression &pathExpr) const;
 
    HDSI_API
    SdfPathVector GetInstancerPrimPaths(
        const SdfPathSet &outermostInstancePaths) const;
 
    HDSI_API
    const HdSceneIndexBaseRefPtr &_GetInputSceneIndex() const;
 
private:
 
    friend class _Observer;
 
    class _Observer : public HdSceneIndexObserver
    {
    public:
        _Observer(HdsiExpressionEvaluatingSceneIndexBase *owner)
            : _owner(owner) {}
 
        HDSI_API
        void PrimsAdded(
            const HdSceneIndexBase &sender,
            const AddedPrimEntries &entries) override;
 
        HDSI_API
        void PrimsRemoved(
            const HdSceneIndexBase &sender,
            const RemovedPrimEntries &entries) override;
 
        HDSI_API
        void PrimsDirtied(
            const HdSceneIndexBase &sender,
            const DirtiedPrimEntries &entries) override;
 
        HDSI_API
        void PrimsRenamed(
            const HdSceneIndexBase &sender,
            const RenamedPrimEntries &entries) override;
 
    private:
        HdsiExpressionEvaluatingSceneIndexBase *_owner;
    };
 
    // -----------------------------------------------------------------------
    // Data
    const HdSceneIndexBaseRefPtr _inputSceneIndex;
    const HdCollectionPredicateLibrary _predicateLibrary;
 
    // Note: The proxy view scene index should be created *before* the internal
    // observer to ensure that it has processed any notices before the observer
    // receives them.
    const HdInstanceProxyViewSceneIndexRefPtr _proxyViewSceneIndex;
    _Observer _observer;
};
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif // PXR_IMAGING_HDSI_EXPRESSION_EVALUATING_SCENE_INDEX_BASE_H