OP_OTLDefinition.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:        OP_OTLDefinition.h ( OTL Library, C++)
 *
 * COMMENTS:
 *
 */

#ifndef __OP_OTLDefinition__
#define __OP_OTLDefinition__

#include "OP_API.h"
#include "OP_Node.h"
#include <UT/UT_StringHolder.h>
#include <UT/UT_ValArray.h>
#include <UT/UT_Color.h>
#include <iosfwd>
#include <time.h>

class UT_String;
class UT_WorkBuffer;


// In addition to alphanumeric and '_' characters, these are the characters
// that are legal in the operator type name.
// '.' - allowed for version numbering
// ':' - used for namespaces
// '/' - used for namespaces (scoping within another operator, which requires
//       a slash for "table/opname" specification)
#define OTL_LEGAL_OPTYPE_NAME_CHARS     ".:/"

class OP_API OP_ExtraInfoBuffer
{
public:
                            OP_ExtraInfoBuffer() = default;
                            OP_ExtraInfoBuffer(const char *extra_info)
                                { readExtraInfo(extra_info); }

    /// Parses the extra info string.
    /// After this call, you can use the query methods below.
    void                    readExtraInfo(const char *extra_info);

    /// @{ Writes out the extra info state of this object into a string.
    void                    writeExtraInfo(UT_WorkBuffer &extra_info) const;
    void                    writeExtraInfo(UT_String &extra_info) const;
    void                    writeExtraInfo(UT_StringHolder &extra_info) const;
    /// @}

    /// True if this is an old format, to ensure we preserve compatibility
    /// if we re-save.
    bool                    oldFormat() const 
                                { return (myOptions.getNumOptions() == 1) && (myOptions.hasOption("vopnetmask")); }

#define OP_EXTRA_ACCESSOR_COMMON(NAME, TOKEN) \
    const UT_StringHolder &get##NAME##Token() const  \
    {  \
        static constexpr UT_StringLit token(TOKEN); \
        return token.asHolder();  \
    } \
    void            remove##NAME() \
                        { myOptions.removeOption(get##NAME##Token()); } \
    bool            has##NAME() const \
                        { return myOptions.hasOption(get##NAME##Token()); } \
/**/

    // WARNING: You cannot add more boolean accessors as they can't be
    // recognized in earlier versions.
#define OP_EXTRA_ACCESSOR_BOOL(NAME, TOKEN) \
    OP_EXTRA_ACCESSOR_COMMON(NAME, TOKEN) \
    bool            get##NAME() const \
                        { return myOptions.getOptionB(get##NAME##Token()); } \
    void            set##NAME(bool value) \
                        { myOptions.setOptionB(get##NAME##Token(), value); } \
    /**/
#define OP_EXTRA_ACCESSOR_STRING(NAME, TOKEN) \
    OP_EXTRA_ACCESSOR_COMMON(NAME, TOKEN) \
    const UT_StringHolder & \
                    get##NAME() const \
                        { return myOptions.getOptionS(get##NAME##Token()); } \
    void            set##NAME(const UT_StringHolder &value) \
                        { myOptions.setOptionSRaw(get##NAME##Token(),value); } \
    /**/
#define OP_EXTRA_ACCESSOR_INT(NAME, TOKEN) \
    OP_EXTRA_ACCESSOR_COMMON(NAME, TOKEN) \
    exint           get##NAME() const \
                        { return myOptions.getOptionI(get##NAME##Token()); } \
    void            set##NAME(exint value) \
                        { myOptions.setOptionI(get##NAME##Token(),value); } \
    /**/

    // WARNING: You cannot add more boolean accessors as they can't be
    // recognized in earlier versions.
    OP_EXTRA_ACCESSOR_BOOL  (HideDefaultParms, "hidedefaultparms")
    OP_EXTRA_ACCESSOR_BOOL  (HasObjExtParms, "objextparms")
    OP_EXTRA_ACCESSOR_STRING(RepresentativeNodePath, "rep")
    OP_EXTRA_ACCESSOR_STRING(GuideNodePath, "guide")
    OP_EXTRA_ACCESSOR_STRING(OpSubType, "subtype")
    OP_EXTRA_ACCESSOR_STRING(ShaderType, "shadertype")
    OP_EXTRA_ACCESSOR_STRING(RenderMask, "rendermask")
    OP_EXTRA_ACCESSOR_STRING(VopnetMask, "vopnetmask")
    OP_EXTRA_ACCESSOR_STRING(PDGType, "pdgtype")
    OP_EXTRA_ACCESSOR_INT   (AlwaysSync, "alwayssync")
    OP_EXTRA_ACCESSOR_INT   (VisibleOutputs, "visibleoutputs")
    OP_EXTRA_ACCESSOR_STRING(CreateLicenseInfo, "createlicense")

private:
    OP_EXTRA_ACCESSOR_STRING(InputColorsString, "inputcolors")
    OP_EXTRA_ACCESSOR_STRING(OutputColorsString, "outputcolors")

public:
    bool           isBoolToken(const UT_StringRef &name)
    {
        return name == getHideDefaultParmsToken()
            || name == getHasObjExtParmsToken()
            ;
    }
    bool           isIntToken(const UT_StringRef &name)
    {
        return name == getAlwaysSyncToken()
            || name == getVisibleOutputsToken()
            ;
    }

#undef OP_EXTRA_ACCESSOR_COMMON
#undef OP_EXTRA_ACCESSOR_BOOL
#undef OP_EXTRA_ACCESSOR_STRING
#undef OP_EXTRA_ACCESSOR_INT

    bool                    hasInputColors() const { return hasInputColorsString(); }
    void                    removeInputColors() { myInputColors.clear(); removeInputColorsString(); }
    const UT_Array<UT_Color> &getInputColors() const { return myInputColors; }
    void                    setInputColors(const UT_Array<UT_Color> &colors)
                            { 
                                myInputColors = colors; 
                                setInputColorsString(writeColorString(colors));
                            }

    bool                    hasOutputColors() const { return hasOutputColorsString(); }
    void                    removeOutputColors() { myOutputColors.clear(); removeOutputColorsString(); }
    const UT_Array<UT_Color> &getOutputColors() const { return myOutputColors; }
    void                    setOutputColors(const UT_Array<UT_Color> &colors)
                            { 
                                myOutputColors = colors; 
                                setOutputColorsString(writeColorString(colors));
                            }

private:
    static void             readColorString(UT_Array<UT_Color> &colors, const char *str);
    static UT_StringHolder  writeColorString(const UT_Array<UT_Color> &colors);
    UT_Options              myOptions;

    UT_Array<UT_Color>      myInputColors;
    UT_Array<UT_Color>      myOutputColors;
};

class OP_API OP_OTLDefinition
{
public:
             OP_OTLDefinition();

    OP_OTLDefinition(const OP_OTLDefinition &definition) = default;
    OP_OTLDefinition &operator=(const OP_OTLDefinition &src) = default;

    const UT_StringHolder &getName() const
                         { return myName; }
    void                 setName(const UT_StringHolder &name)
                         { myName = name; }
    const UT_StringHolder &getLabel() const
                         { return myLabel; }
    void                 setLabel(const UT_StringHolder &label)
                         { myLabel = label; }
    const UT_StringHolder &getPath() const
                         { return myPath; }
    void                 setPath(const UT_StringHolder &path)
                         { myPath = path; }
    const UT_StringHolder &getIcon() const
                         { return myIcon; }
    void                 setIcon(const UT_StringHolder &icon)
                         { myIcon = icon; }
    UT_StringHolder      getResolvedIcon() const;
    const UT_StringHolder &getAuthor() const
                         { return myAuthor; }
    void                 setAuthor(const UT_StringHolder &author)
                         { myAuthor = author; }
    const UT_StringHolder &getCopyright() const
                         { return myCopyright; }
    void                 setCopyright(const UT_StringHolder &copyright)
                         { myCopyright = copyright; }
    const UT_StringHolder &getOpTableName() const
                         { return myOpTableName; }
    void                 setOpTableName(const UT_StringHolder &optablename)
                         { myOpTableName = optablename; }
    const UT_StringHolder &getIndexPath() const
                         { return myIndexPath; }
    void                 setIndexPath(const UT_StringHolder &indexpath)
                         { myIndexPath = indexpath; }
    const UT_StringHolder &getIndexFile() const
                         { return myIndexFile; }
    void                 setIndexFile(const UT_StringHolder &indexfile)
                         { myIndexFile = indexfile; }
    const UT_StringHolder &getLicenseInfo() const
                         { return myLicenseInfo; }
    void                 setLicenseInfo(const UT_StringHolder &licenseinfo)
                         { myLicenseInfo = licenseinfo; }

    /// Extra operator info.  This is stored as a raw string in the OTL
    /// as the myExtraInfo.  The parsed version of the string is kept in
    /// sync as myExtraInfoBuffer.
    const UT_StringHolder &getExtraInfo() const
                         { return myExtraInfo; }
    void                 setExtraInfo(const UT_StringHolder &extrainfo)
                         { myExtraInfo = extrainfo; 
                           myExtraInfoBuffer.readExtraInfo(extrainfo);
                         }
    const OP_ExtraInfoBuffer &getExtraInfoBuffer() const
                        { return myExtraInfoBuffer; }
    void                setExtraInfoBuffer(const OP_ExtraInfoBuffer &buf)
                        { myExtraInfoBuffer = buf;
                          UT_WorkBuffer extra;
                          buf.writeExtraInfo(extra);
                          myExtraInfo = std::move(extra);
                        }

    const UT_StringHolder &getUserInfo() const
                         { return myUserInfo; }
    void                 setUserInfo(const UT_StringHolder &userinfo)
                         { myUserInfo = userinfo; }
    int                  getMinInputs() const
                         { return myMinInputs; }
    void                 setMinInputs(int inputs)
                         { myMinInputs = inputs; }
    int                  getMaxInputs() const
                         { return myMaxInputs; }
    void                 setMaxInputs(int inputs)
                         { myMaxInputs = inputs; }
    int                  getNumOrderedInputs() const
                         { return myNumOrderedInputs; }
    void                 setNumOrderedInputs(int inputs)
                         { myNumOrderedInputs = inputs; }
    int                  getMaxOutputs() const
                         { return myMaxOutputs; }
    void                 setMaxOutputs(int outputs)
                         { myMaxOutputs = outputs; }
    time_t               getModTime() const
                         { return myModTime; }
    void                 setModTime(time_t modtime)
                         { myModTime = modtime; }
    bool                 getIsSubnet() const
                         { return myIsSubnet; }
    void                 setIsSubnet(bool issubnet)
                         { myIsSubnet = issubnet ? 1 : 0; }
    bool                 getIsPython() const
                         { return myIsPython; }
    void                 setIsPython(bool ispython)
                         { myIsPython = ispython ? 1 : 0; }
    bool                 getIsDummyDefinition() const
                         { return myIsDummyDefinition; }
    void                 setIsDummyDefinition(bool isdummy)
                         { myIsDummyDefinition = isdummy ? 1 : 0; }
    OP_OTLLicenseType    getCachedLicenseType() const
                         { return myCachedLicenseType; }
    void                 setCachedLicenseType(OP_OTLLicenseType type)
                         { myCachedLicenseType = type; }

    /// Return if this is an internally defined operator
    bool                 isInternal() const
                         { return myPath == theInternalPath.asRef(); }

    /// Mark as internal
    void                 setPathToInternal()
                         { setPath(theInternalPath.asHolder()); }

    // Handle options that appear in index files (-icon, -inputs, etc.).
    int                  handleOption(int argc, char *argv[]);
    // Concatenates the op table name and the op name to get a unique name.
    void                 getTableAndName(UT_WorkBuffer &name) const;
    void                 getTableAndName(UT_String &name) const;

    bool                 resolveRelativeOpDefPath(
                                UT_WorkBuffer &result,
                                const char *path) const;

    // Converts the table name into an OP_OpTypeId.
    OP_OpTypeId          getOpTypeId() const;

    bool                         load(UT_IStream &is,
                                      UT_StringHolder *errors = nullptr);
    bool                         save(std::ostream &os);
    // Writes a text description that is easily readable by the user.
    void                         writeTextDescription(UT_WorkBuffer &buffer,
                                      const char *indent = 0) const;
    // Writes a text description based on the format string. The format
    // string is a series of characters. Each character represents one
    // piece of information. The information is output on a single line.
    void                         writeFormattedText(UT_WorkBuffer &buffer,
                                      const char *format) const;
    // Read in a text description written out as above. We return false if an
    // invalid or malformed description is found. We return true if we read in
    // a good description _or_ if we reach the end of the stream before even
    // starting a description.
    bool                         readTextDescription(UT_IStream &is);

    /// Returns an official name of the library section that contains 
    /// the HDA definition eg "Object/hda", or "artistA::Object/hda::2.0".
    /// See UT_OpUtils::getOpTypeDefSectionName() for more details.
    /// @{
    void                 getDefinitionSectionName(UT_String &sectname) const;
    void                 getDefinitionSectionName(UT_WorkBuffer &sectname) const;
    /// @}

    /// Returns an official file path that should be used for a given
    /// definition, eg "oplib:/Object/hda?Object/hda".
    void                 constructDefinitionPath(UT_String &path) const;

    /// Utility function for converting a string to a modification time.
    static time_t        getModTimeFromString(const char *str);

    /// Returns true if the name is a valid operator name that can be used for
    /// an OP_Operator instance.
    static bool          isValidOperatorName(const char *name);

    /// Returns true if op_name includes a namespace and that namesapce
    /// matches the given scope_opname, e.g., op_name of "Object/geo::op" 
    /// matches scope_name of "Object/geo".
    /// If op_name does not include a namespace, it is allowed everywhere,
    /// so it will match any scope, thus this function will return true.
    /// Returns false otherwise.
    static bool          isMatchingNamespaceScope( const char *op_name,
                                            const char *scope_opname );

private:
    UT_StringHolder              myName;
    UT_StringHolder              myLabel;
    UT_StringHolder              myPath;
    UT_StringHolder              myIcon;
    UT_StringHolder              myAuthor;
    UT_StringHolder              myCopyright;
    UT_StringHolder              myOpTableName;
    UT_StringHolder              myIndexPath;
    UT_StringHolder              myIndexFile;
    UT_StringHolder              myLicenseInfo;
    UT_StringHolder              myExtraInfo;
    OP_ExtraInfoBuffer           myExtraInfoBuffer;
    UT_StringHolder              myUserInfo;
    int32                        myMinInputs;
    int32                        myMaxInputs;
    int32                        myNumOrderedInputs;
    int32                        myMaxOutputs;
    time_t                       myModTime;
    char                         myIsSubnet;
    char                         myIsPython;
    char                         myIsDummyDefinition;
    OP_OTLLicenseType            myCachedLicenseType;

    // Path value that marks definition as isInternal()
    static const UT_StringLit    theInternalPath;
};

typedef UT_ValArray<OP_OTLDefinition *> OP_OTLDefinitionArray;

#endif