UT_PropertyTable.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        (UT_PropertyTable.h, C++)
 *
 * COMMENTS:
 */

#ifndef _UT_PropertyTable_
#define _UT_PropertyTable_

#include "UT_API.h"
#include "UT_JSONValue.h"
#include "UT_JSONValueMap.h"
#include "UT_Map.h"
#include "UT_NonCopyable.h"
#include "UT_Options.h"
#include "UT_Set.h"
#include "UT_SharedPtr.h"
#include "UT_SymbolTable.h"

/// This class represents a table of (mantra) properties. A property consists
/// of a name (the name used by mantra), a parm name (the name of the houdini
/// parameter that corresponds to the mantra property), the data type of the
/// property, and the default value of the property.
///
/// This information is somewhat scattered right now, with the parameter
/// definition in the $HH/properties/soho/IFDmantra.ds file, the translation
/// from houdini to mantra names in $HH/soho/base/IFDmantra.py, and the
/// defaults as mantra understands them (which should but may not match
/// the defaults in the parameter definitions) in $RAY/RAY_Settings.C.
/// At some point all references to render properties should be through
/// this class.
///
/// The property table is loaded from a JSON array where each item in the array
/// is a dictionary defining a property.  The items to define the property are:
///     - "string class" (required): Specifies the rendering class of the
///        property (i.e. "renderer", "object"  or "option")
///     - "string name" (required): The renderer name for the property
///     - "string hname" (required): The name of the Houdini parameter
///     - "<type> default" (required): The default value.  This may be one of:
///             - bool
///             - number
///             - string
///             - array of numbers
///             - array of strings
///     - "string label" (optional): The label of the Houdini parameter
///     - "float min" (optional): Suggested minimum value for numeric types
///     - "float max" (optional): Suggested maximum value for numeric types
///
class UT_API UT_PropertyTable
{
public:
    using OptionEntryPtr = UT_SharedPtr<UT_OptionEntry>;

    UT_PropertyTable(const char *table_name,
            bool verbose=false);
    UT_PropertyTable(UT_JSONParser &p,
                    const char *filename=nullptr,
                    bool verbose=false);

    /// Return the load status of the table in the c-tor.
    bool                         loadStatus() const { return myLoadStatus; }

    SYS_DEPRECATED(16.0)        // Use size()
    int                          getNumProps() const { return size(); }
    SYS_DEPRECATED(16.0)        // Use findRName()
    int                          getPropIndex(const UT_StringRef &name)
                                        { return findRName(name); }

    SYS_DEPRECATED(16.0)
    const UT_StringHolder       &getPropName(int i) const { return rname(i); }
    SYS_DEPRECATED(16.0)
    const UT_StringHolder       &getPropLabel(int i) const { return label(i); }
    SYS_DEPRECATED(16.0)
    const UT_StringHolder       &getPropParm(int i) const { return hname(i); }
    SYS_DEPRECATED(16.0)
    OptionEntryPtr               getPropDefault(int i) const { return value(i);}
    SYS_DEPRECATED(16.0)
    fpreal64                     getMin(int i) const { return minValue(i); }
    SYS_DEPRECATED(16.0)
    fpreal64                     getMax(int i) const { return maxValue(i); }

    /// Find a property by the renderer property name.  This will find names
    /// like "global:lod", but also "lod".  The first usage (with class
    /// specifier) avoids name aliasing between different rendering classes.
    /// The method returns @c -1 if the property isn't found.
    int                 findRName(const UT_StringRef &name) const;
    /// Find property by the Houdini parameter name
    /// The method returns @c -1 if the parameter isn't found.
    int                 findHName(const UT_StringRef &name) const;

    /// Number of properties stored in the table
    exint                        size() const { return myProperties.size(); }
    /// Return the class of the rendering property (i.e. "object")
    const UT_StringHolder       &rclass(int i) const;
    /// Return the name of the rendering property (i.e. "coving")
    const UT_StringHolder       &rname(int i) const;
    /// Return the name of the houdini parameter (i.e. "vm_coving")
    const UT_StringHolder       &hname(int i) const;
    /// Return the label of the houdini parameter (i.e. "Coving")
    const UT_StringHolder       &label(int i) const;
    /// Return the default value of the houdini parameter (i.e. 1)
    OptionEntryPtr               value(int i) const;
    /// @{
    /// For numeric values, return the expected range of the values.  These is
    /// typically a suggested range.
    fpreal64                     minValue(int i) const;
    fpreal64                     maxValue(int i) const;
    /// @}

    /// Return a raw JSONValueMap representing the property
    const UT_JSONValueMap       &jsonMap(int i) const
                                    { return myProperties[i].jsonMap(); }

    /// @{
    /// Import a value from a property
    template <typename T> SYS_FORCE_INLINE bool
    import(int idx, const UT_StringRef &name, T &val) const
        { return myProperties[idx].import(name, val); }

    template <typename T> SYS_FORCE_INLINE bool
    import(int idx, const UT_StringRef &name, T *val, int size) const
        { return myProperties[idx].import(name, val, size); }
    /// @}

    /// Debug the settings
    bool        save(UT_JSONWriter &w, const UT_IntArray *select=nullptr) const;
    void        dump(const UT_IntArray *select=nullptr) const;

    /// Relatively lightweight representation of a subset of a UT_PropertyList.
    class PropertySubsetList
    {
    public:
         PropertySubsetList(const UT_PropertyTable &table)
             : myTable(table)
         {
         }

        /// @{
        /// Interface to properties
        exint                    size() const   { return myProperties.size(); }
        const UT_StringHolder   &rclass(int i) const
                                    { return myTable.rclass(map(i)); }
        const UT_StringHolder   &rname(int i) const
                                    { return myTable.rname(map(i)); }
        const UT_StringHolder   &hname(int i) const
                                    { return myTable.hname(map(i)); }
        const UT_StringHolder   &label(int i) const
                                    { return myTable.label(map(i)); }
        OptionEntryPtr           value(int i) const
                                    { return myTable.value(map(i)); }
        fpreal64                 minValue(int i) const
                                    { return myTable.minValue(map(i)); }
        fpreal64                 maxValue(int i) const
                                    { return myTable.maxValue(map(i)); }

        bool    save(UT_JSONWriter &w) const
                    { return myTable.save(w, &myProperties); }
        void    dump() const
                    { return myTable.dump(&myProperties); }
        /// @}

        /// Get the index in the parent table
        exint   parentIndex(int i) const        { return map(i); }

        /// Add a property using the index from the base table
        void    appendProperty(int id)  { myProperties.append(id); }

    private:
        int     map(int i) const
        {
            return i >= 0 && i < myProperties.size() ? myProperties(i) : -1;
        }
        const UT_PropertyTable  &myTable;
        UT_IntArray              myProperties;
    };

    const PropertySubsetList    &getSubset(const UT_StringRef &name)
                                    { return getSubset(&name, 1); }
    const PropertySubsetList    &getSubset(const UT_StringRef names[],
                                            exint arraylen);

    /// Function to extract a list of properties as an array of UT_JSONValueMaps
    /// The SELECT method takes a const reference to the UT_JSONValueMap and
    /// should return true if the map should be added.  For example, to find
    /// all the karma global rendering properties, you can do something like:
    /// @code
    ///    UT_Array<const UT_JSONValueMap *> globals;
    ///    ptable.select(globals, [](const UT_JSONValueMap &prop)
    ///    {
    ///        UT_StringHolder _renderer;
    ///        UT_StringHolder _class;
    ///        return prop.import("renderer", _renderer)
    ///            && prop.import("class", _class)
    ///            && renderer == "karma"
    ///            && _class == "global";
    ///    });
    /// @endcode
    template <typename SELECT> SYS_FORCE_INLINE void
    select(UT_Array<const UT_JSONValueMap *> &matched, SELECT &predicate)
    {
        for (auto &&pdef : myProperties)
        {
            if (predicate(pdef.jsonMap()))
                matched.append(&pdef.jsonMap());
        }
    }
    /// Run an operation on a selection of properties from the table.
    /// The SELECT method takes a const reference to the UT_JSONValueMap and
    /// should return true if the functor should be called.
    template <typename FUNC, typename SELECT> SYS_FORCE_INLINE void
    filter(FUNC &func, SELECT &predicate)
    {
        for (auto &&pdef : myProperties)
        {
            if (predicate(pdef.jsonMap()))
                FUNC(pdef.jsonMap());
        }
    }

private:
    struct IncludeGuards
    {
        IncludeGuards(bool v=false)
            : myVerbose(v)
        {
        }

        // Verbose if the flag is set and we haven't included any files
        bool    verbose() const { return myVerbose && mySet.size() == 0; }
        void    insert(const UT_StringRef &r) { mySet.insert(r); }
        void    erase(const UT_StringRef &r) { mySet.erase(r); }
        size_t  count(const UT_StringRef &r) const { return mySet.count(r); }
        size_t  size() const { return mySet.size(); }
        UT_Set<UT_StringRef>    mySet;
        bool                    myVerbose;
    };
    bool                         doInclude(const UT_StringRef &filename,
                                        IncludeGuards &guards);
    bool                         load(UT_IStream &is, IncludeGuards &guards);
    bool                         load(UT_JSONParser &p,
                                        const char *filename,
                                        IncludeGuards &guards);
    const PropertySubsetList    &buildSubset(const UT_StringRef names[],
                                            exint arraylen,
                                            const UT_StringHolder &key);

    using PropertySubsetListMap = UT_Map<UT_StringHolder, PropertySubsetList>;

    class PropDef
    {
    public:
        PropDef(UT_JSONValueMap *map);
        ~PropDef();

        UT_NON_COPYABLE(PropDef)

        /// Saves out a dictionary for the property
        bool    save(UT_JSONWriter &w) const;

        const UT_StringHolder   &rclass() const { return myRClass; }
        const UT_StringHolder   &rname() const  { return myRName; }
        const UT_StringHolder   &hname() const  { return myHName; }
        const UT_StringHolder   &label() const  { return myLabel; }
        const OptionEntryPtr    &value() const  { return myValue; }
        fpreal64                 minValue() const       { return myMin; }
        fpreal64                 maxValue() const       { return myMax; }
        const UT_JSONValueMap   &jsonMap() const        { return *myJSONMap; }
        const UT_JSONValue      *getItem(const UT_StringRef &name)
                                    { return (*myJSONMap)(name); }

        template <typename T> SYS_FORCE_INLINE bool
        import(const UT_StringRef &name, T &v)
        {
            const UT_JSONValue  *item = (*myJSONMap)(name);
            return item && item->import(v);
        }
        template <typename T> SYS_FORCE_INLINE bool
        import(const UT_StringRef &name, T *v, int size)
        {
            const UT_JSONValue  *item = (*myJSONMap)(name);
            return item && item->import(v, size);
        }
    private:
        UT_JSONValueMap *myJSONMap;
        UT_StringHolder  myRClass;
        UT_StringHolder  myRName;
        UT_StringHolder  myHName;
        UT_StringHolder  myLabel;
        OptionEntryPtr   myValue;
        fpreal64         myMin;
        fpreal64         myMax;
    };
    void        addProperty(const UT_JSONValueMap &map);

    UT_Array<PropDef>           myProperties;
    UT_SymbolMap<int>           myRNameMap;
    UT_SymbolMap<int>           myHNameMap;
    PropertySubsetListMap       mySubsets;
    bool                        myLoadStatus;
};

#endif