shaderNodeMetadata.h

//
// Copyright 2025 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//

#ifndef PXR_USD_SDR_SHADER_NODE_METADATA_H
#define PXR_USD_SDR_SHADER_NODE_METADATA_H

#include "pxr/pxr.h"
#include "pxr/base/tf/staticTokens.h"
#include "pxr/base/vt/dictionary.h"
#include "pxr/usd/sdr/api.h"
#include "pxr/usd/sdr/declare.h"

PXR_NAMESPACE_OPEN_SCOPE

// Note: Metadata keys that are generated by parsers should start with
// "__SDR__" to reduce the risk of collision with metadata actually in the
// shader.
//
// Enum names should correlate directly to named API e.g. "GetLabel" or
// "GetSdrUsdEncodingVersion"
#define SDR_NODE_METADATA_TOKENS                         \
    ((Category, "category")) /* deprecated */            \
    ((Domain, "domain"))                                 \
    ((Subdomain, "subdomain"))                           \
    ((Context, "context"))                               \
    ((Role, "role"))                                     \
    ((TargetRenderer, "targetRenderer"))                 \
    ((Collections, "collections"))                       \
    ((Departments, "departments")) /* deprecated */      \
    ((Help, "help"))                                     \
    ((Label, "label"))                                   \
    ((Pages, "pages")) /* deprecated */                  \
    ((OpenPages, "openPages"))                           \
    ((PagesShownIf, "pagesShownIf"))                     \
    ((Primvars, "primvars"))                             \
    ((ImplementationName, "__SDR__implementationName"))  \
    ((Target, "__SDR__target")) /* deprecated */         \
    ((SdrUsdEncodingVersion, "sdrUsdEncodingVersion"))   \
    ((SdrDefinitionNameFallbackPrefix, "sdrDefinitionNameFallbackPrefix"))

#define SDR_NODE_DOMAIN_TOKENS  \
    ((Rendering, "rendering"))  \
    ((General, "general"))

#define SDR_NODE_SUBDOMAIN_TOKENS  \
    /* rendering domain */         \
    ((Shading, "shading"))         \
    ((Filtering, "filtering"))     \
    ((Lighting, "lighting"))       \
    ((Rendering, "rendering"))

#define SDR_NODE_CONTEXT_TOKENS         \
    /* shading subdomain */             \
    ((Pattern, "pattern"))              \
    ((Surface, "surface"))              \
    ((Volume, "volume"))                \
    ((Displacement, "displacement"))    \
    /* lighting subdomain */            \
    ((Light, "light"))                  \
    ((LightFilter, "lightFilter"))      \
    /* filtering subdomain*/            \
    ((DisplayFilter, "displayFilter"))  \
    ((PixelFilter, "pixelFilter"))      \
    ((SampleFilter, "sampleFilter"))    \
    ((VolumeFilter, "volumeFilter"))    \
    ((EnergyFilter, "energyFilter"))    \
    /* rendering subdomain */           \
    ((Integrator, "integrator"))        \
    ((Projection, "projection"))

#define SDR_NODE_ROLE_TOKENS         \
    ((Primvar, "primvar"))           \
    ((Texture, "texture"))           \
    ((Field, "field"))               \
    ((Math, "math"))


TF_DECLARE_PUBLIC_TOKENS(SdrNodeMetadata, SDR_API, SDR_NODE_METADATA_TOKENS);
TF_DECLARE_PUBLIC_TOKENS(SdrNodeDomain, SDR_API, SDR_NODE_DOMAIN_TOKENS);
TF_DECLARE_PUBLIC_TOKENS(SdrNodeSubdomain, SDR_API, SDR_NODE_SUBDOMAIN_TOKENS);
TF_DECLARE_PUBLIC_TOKENS(SdrNodeContext, SDR_API, SDR_NODE_CONTEXT_TOKENS);
TF_DECLARE_PUBLIC_TOKENS(SdrNodeRole, SDR_API, SDR_NODE_ROLE_TOKENS);


class SdrShaderNodeMetadata
{
public:
    SDR_API
    SdrShaderNodeMetadata();

    SDR_API
    SdrShaderNodeMetadata(const SdrTokenMap& legacyMetadata);

    SdrShaderNodeMetadata(
        const std::initializer_list<std::pair<TfToken, std::string>>& init
    ): SdrShaderNodeMetadata(_LegacyCtorFromInitializer(init)) {}

    SDR_API
    explicit SdrShaderNodeMetadata(const VtDictionary& items);

    SDR_API
    bool HasItem(const TfToken& key) const;

    SDR_API
    void SetItem(const TfToken& key, const VtValue& value);

    template <typename T>
    void SetItem(const TfToken& key, const T& value) {
        SetItem(key, VtValue(value));
    }

    SDR_API
    VtValue GetItemValue(const TfToken& key) const;

    template <typename T>
    T GetItemValueAs(const TfToken& key) const {
        const VtValue v = GetItemValue(key);
        if (!v.IsEmpty()) {
            const VtValue converted = VtValue::Cast<T>(v);
            if (!converted.IsEmpty()) {
                return converted.UncheckedGet<T>();
            }
        }

        return {};
    }

    SDR_API
    void ClearItem(const TfToken& key);

    const VtDictionary& GetItems() const & { return _items; }

    VtDictionary GetItems() && { return std::move(_items); }


    SDR_API
    static VtValue GetDefaultValue(const TfToken& key);

    SDR_API
    static const VtDictionary& GetDefaultValues();


    SDR_API
    bool HasLabel() const;
    SDR_API
    TfToken GetLabel() const;
    SDR_API
    void SetLabel(const TfToken& v);
    SDR_API
    void ClearLabel();


    SDR_API
    bool HasCategory() const;
    SDR_API
    TfToken GetCategory() const;
    SDR_API
    void SetCategory(const TfToken& v);
    SDR_API
    void ClearCategory();

    SDR_API
    bool HasDomain() const;
    SDR_API
    TfToken GetDomain() const;
    SDR_API
    void SetDomain(const TfToken& v);
    SDR_API
    void ClearDomain();

    SDR_API
    bool HasSubdomain() const;
    SDR_API
    TfToken GetSubdomain() const;
    SDR_API
    void SetSubdomain(const TfToken& v);
    SDR_API
    void ClearSubdomain();

    SDR_API
    bool HasContext() const;
    SDR_API
    TfToken GetContext() const;
    SDR_API
    void SetContext(const TfToken& v);
    SDR_API
    void ClearContext();

    SDR_API
    bool HasRole() const;
    SDR_API
    TfToken GetRole() const;
    SDR_API
    void SetRole(const TfToken& v);
    SDR_API
    void ClearRole();

    SDR_API
    bool HasTargetRenderer() const;
    SDR_API
    TfToken GetTargetRenderer() const;
    SDR_API
    void SetTargetRenderer(const TfToken& v);
    SDR_API
    void ClearTargetRenderer();

    SDR_API
    bool HasCollections() const;
    SDR_API
    SdrTokenVec GetCollections() const;
    SDR_API
    void SetCollections(const SdrTokenVec& v);
    SDR_API
    void ClearCollections();

    SDR_API
    bool HasHelp() const;
    SDR_API
    std::string GetHelp() const;
    SDR_API
    void SetHelp(const std::string& v);
    SDR_API
    void ClearHelp();


    SDR_API
    bool HasDepartments() const;
    SDR_API
    SdrTokenVec GetDepartments() const;
    SDR_API
    void SetDepartments(const SdrTokenVec& v);
    SDR_API
    void ClearDepartments();

    SDR_API
    bool HasPages() const;
    SDR_API
    SdrTokenVec GetPages() const;
    SDR_API
    void SetPages(const SdrTokenVec& v);
    SDR_API
    void ClearPages();

    SDR_API
    bool HasOpenPages() const;
    SDR_API
    SdrTokenVec GetOpenPages() const;
    SDR_API
    void SetOpenPages(const SdrTokenVec& v);
    SDR_API
    void ClearOpenPages();

    SDR_API
    bool HasPagesShownIf() const;
    SDR_API
    SdrTokenMap GetPagesShownIf() const;
    SDR_API
    void SetPagesShownIf(const SdrTokenMap& v);
    SDR_API
    void ClearPagesShownIf();

    SDR_API
    bool HasPrimvars() const;
    SDR_API
    SdrStringVec GetPrimvars() const;
    SDR_API
    void SetPrimvars(const SdrStringVec& v);
    SDR_API
    void ClearPrimvars();

    SDR_API
    bool HasImplementationName() const;
    SDR_API
    std::string GetImplementationName() const;
    SDR_API
    void SetImplementationName(const std::string& v);
    SDR_API
    void ClearImplementationName();

    SDR_API
    bool HasSdrUsdEncodingVersion() const;
    SDR_API
    int GetSdrUsdEncodingVersion() const;
    SDR_API
    void SetSdrUsdEncodingVersion(const int& v);
    SDR_API
    void ClearSdrUsdEncodingVersion();

    SDR_API
    bool HasSdrDefinitionNameFallbackPrefix() const;
    SDR_API
    std::string GetSdrDefinitionNameFallbackPrefix() const;
    SDR_API
    void SetSdrDefinitionNameFallbackPrefix(const std::string& v);
    SDR_API
    void ClearSdrDefinitionNameFallbackPrefix();


private:
    friend class SdrShaderNode;

    // Deprecated function for legacy metadata support.
    //
    // Unnamed metadata with non-string values are not returned in
    // the legacy map.
    SdrTokenMap _EncodeLegacyMetadata() const;

    static
    SdrTokenMap _LegacyCtorFromInitializer(
        std::initializer_list<std::pair<TfToken, std::string>> f)
    {
        return SdrTokenMap(f.begin(), f.end());
    }

    // This method sets metadata items that have default values
    // as indicated by GetDefaultValues.
    //
    // Note: This method is invoked at the ends of this class's
    // constructors.
    void _SetDefaultInitializations();

    VtDictionary _items;
};

PXR_NAMESPACE_CLOSE_SCOPE

#endif // PXR_USD_SDR_SHADER_NODE_METADATA_H