materialOverrideResolvingSceneIndex.h

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

#include "pxr/base/tf/declarePtrs.h"
#include "pxr/imaging/hd/filteringSceneIndex.h"
#include "pxr/imaging/hd/materialBindingSchema.h"
#include "pxr/imaging/hd/materialOverrideSchema.h"
#include "pxr/imaging/hdsi/api.h"

#include <optional>
#include <unordered_map>
#include <unordered_set>

PXR_NAMESPACE_OPEN_SCOPE

using PathSet = std::unordered_set<SdfPath, SdfPath::Hash>;

TF_DECLARE_WEAK_AND_REF_PTRS(HdsiMaterialOverrideResolvingSceneIndex);

/*
HdsiMaterialOverrideResolvingSceneIndex applies material overrides in the form
of edits to a material's interface or directly to parameters of its shader nodes.

Overrides to a material's interface are only applied if their interface mappings 
are found.
The overrides for a particular 'publicUIName' are specified at path like this:

materialOverride.interfaceValues.<publicUIName>.value 
    -> overrideValueDataSource

The 'overrideValueDataSource' is copied over a network node parameter's original
'valueDataSource' at paths like this:

material.<renderContext>.nodes.<nodePath>.parameters.<inputName>.value
    -> valueDataSource

The scene index identifies which network node parameter to override by using
the material's interface mappings which are defined at paths like this:

material.<renderContext>.interface.parameters.<publicUIName>.mappings 
    -> [(nodePath, inputName), (nodePath, inputName), ...]

Edits of input parameters of shaders within the material are specified at a path 
like this:
materialOverride.parameterValues.<shaderNodeName>.<parameterName>.value ->
    paramEditValueDataSource

The 'paramEditValueDataSource' is copied over a network node parameter's original
'valueDataSource' at paths like this:

material.<renderContext>.nodes.<nodePath>.parameters.<inputName>.value
    -> valueDataSource

If the same input parameter is overridden both by an edit to the material
interface and by a direct parameter edit, the interface override will take 
precedence.

If a geometry prim contains materialOverride data sources, a copy of
the material bound to that location will be generated, and the overrides will
only be applied to the generated material.
Any changes to the original material will be reflected in the generated material.
Geometry prims that contain materialOverride data sources are only
processed by this Scene Index if they contain a materialBindings data source
with material binds for one of the following purposes: full, allPurpose.
A minimum set of materials will be generated to satisfy material overrides: two
geometry prims bound to the same material and containing the same set of
material overrides will share the same generated material.

Below is a diagram of the expected attributes needed for material interface
and parameter edits on a scene index prim of type 'material':

MaterialPrim
|
+------materialOverride
|      |
|      +----interfaceValues
|      |    |
|      |    +-publicUIName
|      |    |   |
|      |    |   +---value -> overrideValueDataSource
|      |    |
|      |    +-publicUIName
|      |    |   |
|      |    |   +---value -> overrideValueDataSource
|      |    |
|      |    +-...
|      |
|      +----parameterValues  
|           |
|           +-nodePath
|           |   |
|           |   +---inputName
|           |   |   |
|           |   |   +---value -> paramEditValueDataSource
|           |   |
|           |   +---inputName
|           |   |   |
|           |   |   +---value -> paramEditValueDataSource
|           |   |
|           |   +---...
|           |  
|           +-...
|
+------material
       |
       +----ri
            |
            +--nodes
            |    |
            |    +-nodePath
            |    |     |
            |    |     +-parameters
            |    |           |
            |    |           +-inputName
            |    |           |   |
            |    |           |   +-value -> valueDataSource
            |    |           |
            |    |           +-inputName
            |    |               |
            |    |               +-value -> valueDataSource
            |    |
            |    +-nodePath  
            |          |
            |          +-parameters           
            |                |
            |                +-...       
            |
            +--interface
                 |
                 +-parameters
                 |     |
                 |     +-publicUIName
                 |     |     |
                 |     |     +-mappings
                 |     |         +-i0
                 |     |         |  |
                 |     |         |  +----nodePath  
                 |     |         |  |
                 |     |         |  +----inputName  
                 |     |         |
                 |     |         +-i1
                 |     |         |  |
                 |     |         |  +----nodePath  
                 |     |         |  |
                 |     |         |  +----inputName  
                 |     |         |
                 |     |         +-...
                 |     |
                 |     +-publicUIName 
                 |     |     |
                 |     |     +-mappings
                 |     |         +-i0
                 |     |         |  |
                 |     |         |  +----nodePath  
                 |     |         |  |
                 |     |         |  +----inputName  
                 |     |         |
                 |     |         +-i1
                 |     |         |  |
                 |     |         |  +----nodePath  
                 |     |         |  |
                 |     |         |  +----inputName  
                 |     |         |
                 |     |         +-...
                 |     +-...
                 |
                 +-parameterOrder = ...
*/

class HdsiMaterialOverrideResolvingSceneIndex final : 
    public HdSingleInputFilteringSceneIndexBase
{
    // Forward Declarations
    struct MaterialData;
    struct PrimData;

    // Type Definitions
    using PrimDataMap = std::unordered_map<SdfPath, PrimData, SdfPath::Hash>;
    using MaterialPathsMap = std::unordered_map<SdfPath, PathSet, SdfPath::Hash>;
    using MaterialDataMap = std::unordered_map<SdfPath, MaterialData, 
        SdfPath::Hash>;
    using HashToMaterialPathMap = std::unordered_map<uint64_t, SdfPath>;
    using MaterialHashMap = std::unordered_map<SdfPath, HashToMaterialPathMap, 
        SdfPath::Hash>;

public:
    static HdsiMaterialOverrideResolvingSceneIndexRefPtr New(
        const HdSceneIndexBaseRefPtr &inputScene)
    {
        return TfCreateRefPtr(
            new HdsiMaterialOverrideResolvingSceneIndex(inputScene));
    }

    // HdSceneIndexBase overrides
    HDSI_API 
    HdSceneIndexPrim GetPrim(const SdfPath &primPath) const override;

    HDSI_API
    SdfPathVector GetChildPrimPaths(const SdfPath &primPath) const override;

protected:

    HDSI_API
    HdsiMaterialOverrideResolvingSceneIndex(
        const HdSceneIndexBaseRefPtr &inputScene);

    // HdSingleInputFilteringSceneIndexBase overrides
    void _PrimsAdded(
        const HdSceneIndexBase &sender,
        const HdSceneIndexObserver::AddedPrimEntries &entries) override;

    void _PrimsRemoved(
        const HdSceneIndexBase &sender,
        const HdSceneIndexObserver::RemovedPrimEntries &entries) override;

    void _PrimsDirtied(
        const HdSceneIndexBase &sender,
        const HdSceneIndexObserver::DirtiedPrimEntries &entries) override;

private:
    HdMaterialOverrideSchema _GetMaterialOverrides(
        const SdfPath& primPath) const;

    HdSceneIndexObserver::AddedPrimEntries _AddGeneratedMaterials(
        const HdSceneIndexObserver::AddedPrimEntries& entries);

    SdfPath _AddGeneratedMaterial(
        const TfToken& primType, 
        const SdfPath& primPath);

    HdSceneIndexObserver::DirtiedPrimEntries _DirtyGeneratedMaterials(
        const HdSceneIndexObserver::DirtiedPrimEntries& entries);

    void _DirtyBaseMaterial(
        const SdfPath& primPath,
        const PathSet& generatedMaterials,
        PathSet* dirtiedPaths) const;

    void _DirtyGeometry(
        const HdSceneIndexObserver::DirtiedPrimEntry& entry,
        const HdSceneIndexBaseRefPtr inputScene,
        const PrimData& primData,
        PathSet* processedPrimsSet,
        PathSet* addedPaths,
        PathSet* dirtiedPaths,
        PathSet* removedPaths);

    void _DirtyMaterialOverrideLocator(
        const SdfPath& primPath,
        const HdSceneIndexBaseRefPtr inputScene,
        PathSet* addedPaths,
        PathSet* dirtiedPaths);

    PathSet _GetGeneratedMaterials(const SdfPath& primPath) const;

    bool _IsGeneratedMaterial(const SdfPath& primPath) const;

    void _CreateGeneratedMaterialDataSource(
        HdSceneIndexPrim& prim,
        const SdfPath& primPath) const;

    uint64_t _GetHash(const HdMaterialOverrideSchema& materialOverrides) const;

    void _InvalidateMaps(const SdfPath& primPath);

    struct MaterialData
    {
        // Path to the material bound to materialOverridePrimPath
        // before any changes are made by this scene index
        SdfPath originalMaterialPath;

        // Set of geometry prims using this generated material
        PathSet boundPrims;
    };

    struct PrimData
    {
        // Path to the generated material bound to this geometry prim
        SdfPath generatedMaterialPath;

        // Hash of the material overrides found on this prim
        uint64_t materialOverrideHash;
    };

    // Map linking a path of a material scope to a set of materials that are 
    // generated by this scene index as a result of resolving material
    // overrides at non-material locations.
    MaterialPathsMap _scopeToNewMaterialPaths;

    // Map linking a material to a set of materials generated from it.
    MaterialPathsMap _oldToNewMaterialPaths;

    // Map linking geometry prims to the path of the generated material that
    // will be bound to them and to the hash for their material overrides.
    // The keys in this map represent geometry prims that have
    // a material binding and a material override data source.
    PrimDataMap _primData;

    // Map linking materials generated in the process of resolving material
    // overrides to their data.
    MaterialDataMap _materialData;

    // Map relating a geometry prim's bound material (before this scene index
    // executes) and the hash of its material override data source to the path
    // of a generated material.
    // Used to allow multiple geometry prims that share the same starting 
    // material and material overrides to use the same generated material.
    // For example:
    // PlasticMaterial --> ..0123 --> __MOR_PlasticMaterial_Mesh
    //                 --> ..4567 --> __MOR_PlasticMaterial_AnotherMesh
    // WoodMaterial    --> ..0123 --> __MOR_WoodMaterial_Mesh
    // MetalMaterial   --> ..4567 --> __MOR_MetalMaterial_Point
    MaterialHashMap _materialHashMap;
};

PXR_NAMESPACE_CLOSE_SCOPE

#endif // PXR_IMAGING_HDSI_MATERIAL_OVERRIDE_RESOLVING_SCENE_INDEX_H