shaderPropertyMetadata.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_PROPERTY_METADATA_H
#define PXR_USD_SDR_SHADER_PROPERTY_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.
#define SDR_PROPERTY_METADATA_TOKENS                 \
    ((Label, "label"))                               \
    ((Help, "help"))                                 \
    ((Page, "page"))                                 \
    ((RenderType, "renderType"))                     \
    ((Role, "role"))                                 \
    ((Widget, "widget"))                             \
    ((Hints, "hints"))                               \
    ((Options, "options"))                           \
    ((IsDynamicArray, "isDynamicArray"))             \
    ((TupleSize, "tupleSize"))                       \
    ((Connectable, "connectable"))                   \
    ((Tag, "tag"))                                   \
    ((ShownIf, "shownIf"))                           \
    ((ValidConnectionTypes, "validConnectionTypes")) \
    ((VstructMemberOf, "vstructMemberOf"))           \
    ((VstructMemberName, "vstructMemberName"))       \
    ((VstructConditionalExpr, "vstructConditionalExpr"))\
    ((IsAssetIdentifier, "__SDR__isAssetIdentifier"))\
    ((ImplementationName, "__SDR__implementationName"))\
    ((SdrUsdDefinitionType, "sdrUsdDefinitionType"))\
    ((DefaultInput, "__SDR__defaultinput"))          \
    ((Target, "__SDR__target"))                      \
    ((Colorspace, "__SDR__colorspace"))


// The following tokens are valid values for the metadata "role"
#define SDR_PROPERTY_ROLE_TOKENS \
    ((None, "none"))

#define SDR_PROPERTY_TOKENS \
    ((PageDelimiter, ":"))

TF_DECLARE_PUBLIC_TOKENS(SdrPropertyMetadata, SDR_API, 
                         SDR_PROPERTY_METADATA_TOKENS);
TF_DECLARE_PUBLIC_TOKENS(SdrPropertyRole, SDR_API,
                         SDR_PROPERTY_ROLE_TOKENS);
TF_DECLARE_PUBLIC_TOKENS(SdrPropertyTokens, SDR_API, SDR_PROPERTY_TOKENS);

class SdrShaderPropertyMetadata
{
public:
    SDR_API
    SdrShaderPropertyMetadata(const SdrTokenMap& legacyMetadata);

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

    explicit SdrShaderPropertyMetadata(const VtDictionary& items)
        : _items(items) {}

    explicit SdrShaderPropertyMetadata(VtDictionary&& items)
        : _items(std::move(items)) {}

    SdrShaderPropertyMetadata() {}

    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
    bool HasLabel() const;
    SDR_API
    TfToken GetLabel() const;
    SDR_API
    void SetLabel(const TfToken& v);
    SDR_API
    void ClearLabel();

    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 HasPage() const;
    SDR_API
    TfToken GetPage() const;
    SDR_API
    void SetPage(const TfToken& v);
    SDR_API
    void ClearPage();

    SDR_API
    bool HasRenderType() const;
    SDR_API
    std::string GetRenderType() const;
    SDR_API
    void SetRenderType(const std::string& v);
    SDR_API
    void ClearRenderType();

    SDR_API
    bool HasRole() const;
    SDR_API
    std::string GetRole() const;
    SDR_API
    void SetRole(const std::string& v);
    SDR_API
    void ClearRole();

    SDR_API
    bool HasWidget() const;
    SDR_API
    TfToken GetWidget() const;
    SDR_API
    void SetWidget(const TfToken& v);
    SDR_API
    void ClearWidget();

    SDR_API
    bool HasIsDynamicArray() const;
    SDR_API
    bool GetIsDynamicArray() const;
    SDR_API
    void SetIsDynamicArray(const bool& v);
    SDR_API
    void ClearIsDynamicArray();

    SDR_API
    bool HasTupleSize() const;
    SDR_API
    int GetTupleSize() const;
    SDR_API
    void SetTupleSize(const int& v);
    SDR_API
    void ClearTupleSize();

    SDR_API
    bool HasConnectable() const;
    SDR_API
    bool GetConnectable() const;
    SDR_API
    void SetConnectable(const bool& v);
    SDR_API
    void ClearConnectable();

    SDR_API
    bool HasShownIf() const;
    SDR_API
    std::string GetShownIf() const;
    SDR_API
    void SetShownIf(const std::string& v);
    SDR_API
    void ClearShownIf();

    SDR_API
    bool HasValidConnectionTypes() const;
    SDR_API
    SdrTokenVec GetValidConnectionTypes() const;
    SDR_API
    void SetValidConnectionTypes(const SdrTokenVec& v);
    SDR_API
    void ClearValidConnectionTypes();

    SDR_API
    bool HasIsAssetIdentifier() const;
    SDR_API
    bool GetIsAssetIdentifier() const;
    SDR_API
    void SetIsAssetIdentifier(const bool& v);
    SDR_API
    void ClearIsAssetIdentifier();

    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 HasSdrUsdDefinitionType() const;
    SDR_API
    TfToken GetSdrUsdDefinitionType() const;
    SDR_API
    void SetSdrUsdDefinitionType(const TfToken& v);
    SDR_API
    void ClearSdrUsdDefinitionType();

    SDR_API
    bool HasDefaultInput() const;
    SDR_API
    bool GetDefaultInput() const;
    SDR_API
    void SetDefaultInput(const bool& v);
    SDR_API
    void ClearDefaultInput();

    SDR_API
    bool HasColorspace() const;
    SDR_API
    TfToken GetColorspace() const;
    SDR_API
    void SetColorspace(const TfToken& v);
    SDR_API
    void ClearColorspace();


private:
    friend class SdrShaderProperty;

    // 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());
    }

    VtDictionary _items;
};

PXR_NAMESPACE_CLOSE_SCOPE

#endif // PXR_USD_SDR_SHADER_PROPERTY_METADATA_H